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
This commit is contained in:
Kristian Dupont
GitHub
parent
9d1d970b1f
commit
70437745f0
|
|
@ -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() {}
|
||||
}
|
||||
|
|
@ -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
|
||||
|
|
|
|||
84
docs/sync.js
84
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.
|
||||
* This Realm can be used to control access and permissions for Realms owned by the user. This includes
|
||||
* giving other users access to Realms.
|
||||
* Gets the server URL that was used for authentication.
|
||||
* @type {string}
|
||||
*/
|
||||
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() {}
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue