Add Session and some missing User docs (#828)

* Add Session and some missing User docs

* Remove accidentally pasted line

* Add permissions docs

* Respond to PR comments

* Remove docs for user.create

docs/permission.js

@@ -0,0 +1,231 @@
+////////////////////////////////////////////////////////////////////////////
+//
+// Copyright 2016 Realm Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Objects of this class allow to change permissions of owned Realms.
+ * They are created exclusively by the client and are processed by the server
+ * as indicated by the status fields.
+ * PermissionChange objects allow to grant and revoke permissions by setting
+ * mayRead, mayWrite and mayManage accordingly. 
+ * If any of these flags are not set, these are merged
+ * with either the existing or default permissions as applicable. As a
+ * side-effect this causes that the default permissions are permanently
+ * materialized for the affected Realm files and the affected user.
+ * Once the request has been processed, the Status, StatusMessage, and
+ * ErrorCode will be updated accordingly.
+ */
+class PermissionChange {
+
+    /**
+     * Gets the unique identifier of this object in the Management realm.
+     * @type {string}
+     */
+    get id() {}
+
+    /**
+     * Gets the creation time of this object.
+     * @type {Date} 
+     */
+    get createdAt() {}
+
+    /**
+     * Gets when the object was updated the last time.
+     * @type {Date} 
+     */
+    get updatedAt() {}
+
+    /**
+     * 
+     */
+    get statusCode() {}
+
+    /**
+     * A detailed message describing the status (success, error) of the operation. null if the object
+     * has not been processed yet.
+     * Filled by the server after an object was processed with additional info
+     * explaining the status if necessary.
+     */
+    get statusMessage() {}
+
+    /**
+     * The identifier of the user who will have changed permissions
+     * @type {string}
+     */
+    get userId() {}
+
+    /**
+     * The URL for the Realm that the changes should apply to.
+     * @type {string}
+     */
+    get realmUrl() {}
+
+    /**
+     * Should the user be allowed to read from the Realm?
+     * @type {bool}
+     */
+    get mayRead() {}
+
+    /**
+     * Should the user be allowed to write to the Realm?
+     * @type {bool}
+     */
+    get mayWrite() {}
+
+    /**
+     * Should the user be allowed to manage the Realm?
+     * @type {bool}
+     */
+    get mayManage() {}
+}
+
+/**
+ * Objects of this class are used to offer permissions to owned Realms.
+ * They are created exclusively by the client and are processed by the server
+ * as indicated by the status fields.
+ * When offering permissions, you should create the offer and add it to the User's Management Realm.
+ * Once the request has been processed, the statusCode, statusMessage, and
+ * ErrorCode will be updated accordingly.
+ * If the request has been processed successfully, the token will be populated and you can share it
+ * with users you wish to grant permissions to.
+ * If the request has failed, statusMessage will be updated with relevant information about the
+ * failure and statusCode will be set.
+ */
+class PermissionOffer {
+    /**
+     * Gets the unique identifier of this object in the Management realm.
+     * @type {string}
+     */
+    get id() {}
+
+    /**
+     * Gets the creation time of this object.
+     * @type {Date} 
+     */
+    get createdAt() {}
+
+    /**
+     * Gets when the object was updated the last time.
+     * @type {Date} 
+     */
+    get updatedAt() {}
+
+    /**
+     * 
+     */
+    get statusCode() {}
+
+    /**
+     * A detailed message describing the status (success, error) of the operation. null if the object
+     * has not been processed yet.
+     * Filled by the server after an object was processed with additional info
+     * explaining the status if necessary.
+     */
+    get statusMessage() {}
+
+    /**
+     * Gets the token that can be used to offer the permissions defined in this object to another user.
+     * @type {string}
+     */
+    get token() {}
+
+    /**
+     * The URL for the Realm that the changes should apply to.
+     * @type {string}
+     */
+    get realmUrl() {}
+
+    /**
+     * Should the user be allowed to read from the Realm?
+     * @type {bool}
+     */
+    get mayRead() {}
+
+    /**
+     * Should the user be allowed to write to the Realm?
+     * @type {bool}
+     */
+    get mayWrite() {}
+
+    /**
+     * Should the user be allowed to manage the Realm?
+     * @type {bool}
+     */
+    get mayManage() {}
+
+    /**
+     * Gets or sets the expiration date and time of the offer.
+     * If null, the offer will never expire. Otherwise, the offer may not be consumed past the expiration date.
+     * @type {Date}
+     */
+    get expiresAt() {}
+}
+
+/**
+ * Objects of this class are used to accept a PermissionOffer using a provided token.
+ * Create an instance of PermissionOfferResponse using the provided PermissionOffer.token
+ * and add it to the user's ManagementRealm.
+ * Once the request has been processed, the statusCode and statusMessage will be updated accordingly.
+ * If the request has been processed successfully, the realmUrl will be populated and you can use it
+ * to connect to the Realm.
+ * If the request has failed, the statusMessage will be updated with relevant information about the
+ * failure and statusCode will be set.
+ */
+class PermissionOfferResponse {
+    /**
+     * Gets the unique identifier of this object in the Management realm.
+     * @type {string}
+     */
+    get id() {}
+
+    /**
+     * Gets the creation time of this object.
+     * @type {Date} 
+     */
+    get createdAt() {}
+
+    /**
+     * Gets when the object was updated the last time.
+     * @type {Date} 
+     */
+    get updatedAt() {}
+
+    /**
+     * 
+     */
+    get statusCode() {}
+
+    /**
+     * A detailed message describing the status (success, error) of the operation. null if the object
+     * has not been processed yet.
+     * Filled by the server after an object was processed with additional info
+     * explaining the status if necessary.
+     */
+    get statusMessage() {}
+
+    /**
+     * Gets the token that can be used to offer the permissions defined in this object to another user.
+     * @type {string}
+     */
+    get token() {}
+
+    /**
+     * The URL for the Realm that the changes should apply to.
+     * @type {string}
+     */
+    get realmUrl() {}
+}

docs/realm.js

@@ -56,6 +56,12 @@ class Realm {
     */
     get schemaVersion() {}
 
+    /**
+     * Gets the sync session if this is a synced Realm
+     * @type {Session}
+     */
+    get syncSession() {}
+
     /**
      * Create a new `Realm` instance using the provided `config`. If a Realm does not yet exist
      * at `config.path` (or {@link Realm.defaultPath} if not provided), then this constructor

docs/sync.js

@@ -55,6 +55,7 @@ class Sync {
 	 */
 	static setLogLevel(log_level) {}
 
+
 }
 
 /**
@@ -149,15 +150,15 @@ class User {
 	static loginWithProvider(server, provider, providerToken, callback) {}
 
 	/**
-	 * Create a new user using the username/password provider
+	 * Register a sync user with username and password.
 	 * @param {string} server - authentication server
 	 * @param {string} username
 	 * @param {string} password
-	 * @param {function(error, User)} callback - called with the following arguments:
+	 * @param {function(error, user)} callback - called with the following arguments:
 	 *   - `error` - an Error object is provided on failure
 	 *   - `user` - a valid User object on success
 	 */
-	static create(server, username, password, callback) {}
+	static register(server, username, password, callback) {}
 
 	/**
 	 * Create an admin user for the given authentication server with an existing token
@@ -181,10 +182,79 @@ class User {
 	static get current() {}
 	
 	/**
-	 * Returns an instance of the Management Realm owned by the user.
+	 * Gets the server URL that was used for authentication.
-	 * This Realm can be used to control access and permissions for Realms owned by the user. This includes
+	 * @type {string}
-	 * giving other users access to Realms.
+	 */
+	get server() {}
+
+	/**
+	 * Gets the identity of this user on the Realm Object Server. 
+	 * The identity is a guaranteed to be unique among all users on the Realm Object Server.
+	 * @type {string}
+	 */
+	get identity() {}
+
+	/**
+	 * Gets this user's refresh token. This is the user's credential for accessing the Realm 
+	 * Object Server and should be treated as sensitive data.
+	 * @type {string}
+	 */
+	get token() {}
+
+	/**
+	 * Returns true if this user is an administrator
+	 * @type {bool}
+	 */
+	get isAdmin() {}
+
+	/**
+	 * Logs out the user from the Realm Object Server.
+	 */
+	logout() {}
+
+	/**
+	 * Get the management realm for this User.
+	 * This Realm can be used to control access and permissions for Realms owned by the user.
+	 * This includes giving others access to the Realms.
 	 * @returns {Realm}
 	 */
-	openAdminRealm() {}
+	openManagementRealm() {}
+}
+
+/**
+ * An object encapsulating a Realm Object Server session. Sessions represent the communication between the 
+ * client (and a local Realm file on disk), and the server (and a remote Realm at a given URL stored on a Realm Object Server).
+ * Sessions are always created by the SDK and vended out through various APIs. The lifespans of sessions 
+ * associated with Realms are managed automatically.
+ * @memberof Realm.Sync
+ */
+class Session {
+	/**
+	 * Gets the Sync-part of the configuration that the corresponding Realm was
+	 * constructed with.
+	 * @type {object}
+	 */
+	get config() {}
+
+	/**
+	 * Gets the User that this session was created with.
+	 * @type {User}
+	 */
+	get user() {}
+
+	/**
+	 * Gets the URL of the Realm Object Server that this session is connected to.
+	 * @type {string}
+	 */
+	get url() {}
+
+	/**
+	 * Gets the current state of the session.
+	 * Can be either:
+	 *  - "active": The session is connected to the Realm Object Server and is actively transferring data.
+	 *  - "inactive": The session is not currently communicating with the Realm Object Server.
+	 *  - "invalid": A non-recoverable error has occurred, and this session is semantically invalid. A new session should be created.
+	 * @type {string}
+	 */
+	get state() {}
 }