para-client-js

/** * JavaScript client for communicating with a Para API server. * @param {String} accessKey Para access key * @param {String} secretKey Para access key * @param {Object} options * @property {String} endpoint the API endpoint (default: paraio.com) * @property {String} apiPath the request path (default: /v1/) * @author Alex Bogdanovski <alex@erudika.com> */ export default class ParaClient { constructor(accessKey: any, secretKey: any, options: any); accessKey: any; endpoint: any; apiPath: any; apiRequestTimeout: any; tokenKey: any; tokenKeyExpires: any; tokenKeyNextRefresh: any; getFullPath: (resourcePath: any) => any; setSecret: (sec: any) => void; /** * Clears the JWT token from memory, if such exists. */ clearAccessToken: () => void; /** * @returns the JWT access token, or null if not signed in */ getAccessToken: () => any; /** * Sets the JWT access token. * @param {String} token a valid token */ setAccessToken: (token: string) => void; /** * @param {Function} fn callback (optional) * @returns {Promise} the version of Para server */ getServerVersion: (fn: Function) => Promise<any>; /** * Invoke a GET request to the Para API. * @param {String} resourcePath the subpath after '/v1/', should not start with '/' * @param {Object} params query parameters * @returns {Object} response */ invokeGet: (resourcePath: string, params: any) => any; /** * Invoke a POST request to the Para API. * @param {String} resourcePath the subpath after '/v1/', should not start with '/' * @param {Object} entity request body * @returns {Object} response */ invokePost: (resourcePath: string, entity: any) => any; /** * Invoke a PUT request to the Para API. * @param {String} resourcePath the subpath after '/v1/', should not start with '/' * @param {Object} entity request body * @returns {Object} response */ invokePut: (resourcePath: string, entity: any) => any; /** * Invoke a PATCH request to the Para API. * @param {String} resourcePath the subpath after '/v1/', should not start with '/' * @param {Object} entity request body * @returns {Object} response */ invokePatch: (resourcePath: string, entity: any) => any; /** * Invoke a DELETE request to the Para API. * @param {String} resourcePath the subpath after '/v1/', should not start with '/' * @param {Object} params query parameters * @returns {Object} response */ invokeDelete: (resourcePath: string, params: any) => any; invokeSignedRequest: (httpMethod: any, endpointURL: any, reqPath: any, headers: any, params: any, jsonEntity: any) => Promise<any>; /** * Parses a search query response and extracts the objects from it. * @param {String} queryType type of search query * @param {Object} params query params * @param {Function} fn callback * @returns {Object} response */ find: (queryType: string, params: any, fn: Function) => any; /** * Deserializes a Response object to POJO of some type. * @param {Object} req request * @param {Function} callback callback * @param {Boolean} returnRawJSON true if raw JSON should be returned as string * @returns {Object} a ParaObject */ getEntity: (req: any, callback: Function, returnRawJSON: boolean) => any; /** * Deserializes ParaObjects from a JSON array (the "items:[]" field in search results). * @param {Array} items a list of deserialized maps * @returns {Array} a list of ParaObjects */ getItemsFromList: (items: any[]) => any[]; /** * Converts a list of Maps to a List of ParaObjects, at a given path within the JSON tree structure. * @param {Object} result the response body for an API request * @param {String} at the path (field) where the array of objects is located * @param {Pager} pager a pager * @returns {Array} a list of ParaObjects */ getItemsAt: (result: any, at: string, pager: Pager) => any[]; /** * Converts a list of Maps to a List of ParaObjects. * @param {Object} result the response body for an API request * @param {Pager} pager a pager * @returns {Array} a list of ParaObjects */ getItems: (result: any, pager: Pager) => any[]; /** * Converts a {Pager} object to query parameters. * @param {Pager} pager a pager * @returns {Object} parameters map */ pagerToParams: (pager: Pager) => any; /** * Returns the App for the current access key (appid). * @param {Function} fn callback (optional) * @returns {Promise} a promise */ getApp(fn: Function): Promise<any>; /** * Persists an object to the data store. If the object's type and id are given, * then the request will be a PUT request and any existing object will be * overwritten. * @param {ParaObject} obj the object to create * @param {Function} fn callback (optional) * @returns {Promise} the same object with assigned id or null if not created. */ create(obj: ParaObject, fn: Function): Promise<any>; /** * Retrieves an object from the data store. * @param {String} type the type of the object * @param {String} id the id of the object * @param {Function} fn callback (optional) * @returns {Promise} the retrieved object or null if not found */ read(type: string, id: string, fn: Function): Promise<any>; /** * Updates an object permanently. Supports partial updates. * @param {ParaObject} obj the object to update * @param {Function} fn callback (optional) * @returns {Promise} the updated object */ update(obj: ParaObject, fn: Function): Promise<any>; /** * Deletes an object permanently. * @param {ParaObject} obj object to delete * @param {Function} fn callback (optional) * @returns {Promise} promise */ delete(obj: ParaObject, fn: Function): Promise<any>; /** * Saves multiple objects to the data store. * @param {Array} objects a list of ParaObjects to create * @param {Function} fn callback (optional) * @returns {Promise} a list of objects */ createAll(objects: any[], fn: Function): Promise<any>; /** * Retrieves multiple objects from the data store. * @param {Array} keys a list of object ids * @param {Function} fn callback (optional) * @returns {Promise} a list of objects */ readAll(keys: any[], fn: Function): Promise<any>; /** * Updates multiple objects. * @param {Array} objects a list of ParaObjects to update * @param {Function} fn callback (optional) * @returns {Promise} a list of objects */ updateAll(objects: any[], fn: Function): Promise<any>; /** * Deletes multiple objects. * @param {Function} fn callback (optional) * @param {Array} keys the ids of the objects to delete * @returns {Promise} promise */ deleteAll(keys: any[], fn: Function): Promise<any>; /** * Returns a list all objects found for the given type. * The result is paginated so only one page of items is returned, at a time. * @param {String} type the type of objects to search for * @param {Pager} pager a Pager object * @param {Function} fn callback (optional) * @returns {Promise} a list of objects */ list(type: string, pager: Pager, fn: Function): Promise<any>; /** * Simple id search. * @param {String} id the id * @param {Function} fn callback (optional) * @returns {Promise} the object if found or null */ findById(id: string, fn: Function): Promise<any>; /** * Simple multi id search. * @param {Array} ids a list of ids to search for * @param {Function} fn callback (optional) * @returns {Promise} a list of objects if found or [] */ findByIds(ids: any[], fn: Function): Promise<any>; /** * Search for address objects in a radius of X km from a given point. * @param {String} type the type of object to search for * @param {String} query the query string * @param {Number} radius the radius of the search circle * @param {Number} lat latitude * @param {Number} lng longitude * @param {Pager} pager a Pager object * @param {Function} fn callback (optional) * @returns {Promise} a list of object found */ findNearby(type: string, query: string, radius: number, lat: number, lng: number, pager: Pager, fn: Function): Promise<any>; /** * Searches for objects that have a property which value starts with a given prefix. * @param {String} type the type of object to search for * @param {String} field the property name of an object * @param {String} prefix the prefix * @param {Pager} pager a Pager object * @param {Function} fn callback (optional) * @returns {Promise} a list of object found */ findPrefix(type: string, field: string, prefix: string, pager: Pager, fn: Function): Promise<any>; /** * Simple query string search. This is the basic search method. * @param {String} type the type of object to search for * @param {String} query the query string * @param {Pager} pager a Pager object * @param {Function} fn callback (optional) * @returns {Promise} a list of object found */ findQuery(type: string, query: string, pager: Pager, fn: Function): Promise<any>; /** * Searches within a nested field. The objects of the given type must contain a nested field "nstd". * @param {String} type the type of object to search for * @param {String} field the name of the field to target (within a nested field "nstd") * @param {String} query the query string * @param {Pager} pager a Pager object * @param {Function} fn callback (optional) * @returns {Promise} a list of object found */ findNestedQuery(type: string, field: string, query: string, pager: Pager, fn: Function): Promise<any>; /** * Searches for objects that have similar property values to a given text. A "find like this" query. * @param {String} type the type of object to search for * @param {String} filterKey exclude an object with this key from the results (optional) * @param {Array} fields a list of property names * @param {String} liketext text to compare to * @param {Pager} pager a Pager object * @param {Function} fn callback (optional) * @returns {Promise} a list of object found */ findSimilar(type: string, filterKey: string, fields: any[], liketext: string, pager: Pager, fn: Function): Promise<any>; /** * Searches for objects tagged with one or more tags. * @param {String} type the type of object to search for * @param {Array} tags the list of tags * @param {Pager} pager a Pager object * @param {Function} fn callback (optional) * @returns {Promise} a list of object found */ findTagged(type: string, tags: any[], pager: Pager, fn: Function): Promise<any>; /** * Searches for Tag objects. * This method might be deprecated in the future. * @param {String} keyword the tag keyword to search for * @param {Pager} pager a Pager object * @param {Function} fn callback (optional) * @returns {Promise} a list of object found */ findTags(keyword: string, pager: Pager, fn: Function): Promise<any>; /** * Searches for objects having a property value that is in list of possible values. * @param {String} type the type of object to search for * @param {String} field the property name of an object * @param {Object} terms a map of terms (property values) * @param {Pager} pager a Pager object * @param {Function} fn callback (optional) * @returns {Promise} a list of object found */ findTermInList(type: string, field: string, terms: any, pager: Pager, fn: Function): Promise<any>; /** * Searches for objects that have properties matching some given values. A terms query. * @param {String} type the type of object to search for * @param {Object} terms a map of fields (property names) to terms (property values) * @param {Boolean} matchAll match all terms. If true - AND search, if false - OR search * @param {Pager} pager a Pager object * @param {Function} fn callback (optional) * @returns {Promise} a list of object found */ findTerms(type: string, terms: any, matchAll: boolean, pager: Pager, fn: Function): Promise<any>; /** * Searches for objects that have a property with a value matching a wildcard query. * @param {String} type the type of object to search for * @param {String} field the property name of an object * @param {String} wildcard wildcard query string. For example "cat*". * @param {Pager} pager a Pager object * @param {Function} fn callback (optional) * @returns {Promise} a list of object found */ findWildcard(type: string, field: string, wildcard: string, pager: Pager, fn: Function): Promise<any>; /** * Counts indexed objects matching a set of terms/values. * @param {String} type the type of object to search for * @param {Object} terms a map of fields (property names) to terms (property values) * @param {Function} fn callback (optional) * @returns {Promise} the number of results found */ getCount(type: string, terms: any, fn: Function): Promise<any>; /** * Count the total number of links between this object and another type of object. * @param {ParaObject} obj the object to execute this method on * @param {String} type2 the other type of object * @param {Function} fn callback (optional) * @returns {Promise} the number of links for the given object */ countLinks(obj: ParaObject, type2: string, fn: Function): Promise<any>; /** * Returns all objects linked to the given one. Only applicable to many-to-many relationships. * @param {ParaObject} obj the object to execute this method on * @param {String} type2 the other type of object * @param {Pager} pager a Pager object * @param {Function} fn callback (optional) * @returns {Promise} a list of linked objects */ getLinkedObjects(obj: ParaObject, type2: string, pager: Pager, fn: Function): Promise<any>; /** * Searches through all linked objects in many-to-many relationships. * @param {ParaObject} obj the object to execute this method on * @param {String} type2 the other type of object * @param {String} field the name of the field to target (within a nested field "nstd") * @param {String} query a query string * @param {Pager} pager a Pager object * @param {Function} fn callback (optional) * @returns {Promise} a list of linked objects */ findLinkedObjects(obj: ParaObject, type2: string, field: string, query: string, pager: Pager, fn: Function): Promise<any>; /** * Checks if this object is linked to another. * @param {ParaObject} obj the object to execute this method on * @param {String} type2 the other type of object * @param {String} id2 the other id * @param {Function} fn callback (optional) * @returns {Promise} true if the two are linked */ isLinked(obj: ParaObject, type2: string, id2: string, fn: Function): Promise<any>; /** * Checks if a given object is linked to this one. * @param {ParaObject} obj the object to execute this method on * @param {ParaObject} toObj the other object * @param {Function} fn callback (optional) * @returns {Promise} true if linked */ isLinkedToObject(obj: ParaObject, toObj: ParaObject, fn: Function): Promise<any>; /** * Links an object to this one in a many-to-many relationship. * Only a link is created. Objects are left untouched. * The type of the second object is automatically determined on read. * @param {ParaObject} obj the object to execute this method on * @param {String} id2 the other id * @param {Function} fn callback (optional) * @returns {Promise} the id of the Linker object that is created */ link(obj: ParaObject, id2: string, fn: Function): Promise<any>; /** * Unlinks an object from this one. * Only a link is deleted. Objects are left untouched. * @param {ParaObject} obj the object to execute this method on * @param {String} type2 the other type of object * @param {String} id2 the other id * @param {Function} fn callback (optional) * @returns {Promise} promise */ unlink(obj: ParaObject, type2: string, id2: string, fn: Function): Promise<any>; /** * Unlinks all objects that are linked to this one. * Deletes all Linker objects. * Only the links are deleted. Objects are left untouched. * @param {ParaObject} obj the object to execute this method on * @param {Function} fn callback (optional) * @returns {Promise} promise */ unlinkAll(obj: ParaObject, fn: Function): Promise<any>; /** * Count the total number of child objects for this object. * @param {ParaObject} obj the object to execute this method on * @param {String} type2 the other type of object * @param {Function} fn callback (optional) * @returns {Promise} the number of links */ countChildren(obj: ParaObject, type2: string, fn: Function): Promise<any>; /** * Returns all child objects linked to this object. * @param {ParaObject} obj the object to execute this method on * @param {String} type2 the other type of object * @param {String} field the field name to use as filter * @param {String} term the field value to use as filter * @param {Pager} pager a Pager object * @param {Function} fn callback (optional) * @returns {Promise} a list of ParaObject in a one-to-many relationship with this object */ getChildren(obj: ParaObject, type2: string, field: string, term: string, pager: Pager, fn: Function): Promise<any>; /** * Search through all child objects. Only searches child objects directly * connected to this parent via the `parentid` field. * @param {ParaObject} obj the object to execute this method on * @param {String} type2 the other type of object * @param {String} query a query string * @param {Pager} pager a Pager object * @param {Function} fn callback (optional) * @returns {Promise} a list of ParaObject in a one-to-many relationship with this object */ findChildren(obj: ParaObject, type2: string, query: string, pager: Pager, fn: Function): Promise<any>; /** * Deletes all child objects permanently. * @param {ParaObject} obj the object to execute this method on * @param {String} type2 the other type of object * @param {Function} fn callback (optional) * @returns {Promise} promise */ deleteChildren(obj: ParaObject, type2: string, fn: Function): Promise<any>; /** * Generates a new unique id. * @param {Function} fn callback (optional) * @returns {Promise} a new id */ newId(fn: Function): Promise<any>; /** * Returns the current timestamp. * @param {Function} fn callback (optional) * @returns {Promise} timestamp in milliseconds */ getTimestamp(fn: Function): Promise<any>; /** * Formats a date in a specific format. * @param {String} format the date format * @param {String} locale the locale instance * @param {Function} fn callback (optional) * @returns {Promise} a formatted date */ formatDate(format: string, locale: string, fn: Function): Promise<any>; /** * Converts spaces to dashes. * @param {String} str a string with spaces * @param {String} replaceWith a string to replace spaces with * @param {Function} fn callback (optional) * @returns {Promise} a string with no whitespace */ noSpaces(str: string, replaceWith: string, fn: Function): Promise<any>; /** * Strips all symbols, punctuation, whitespace and control chars from a string. * @param {String} str a dirty string * @param {Function} fn callback (optional) * @returns {Promise} a clean string */ stripAndTrim(str: string, fn: Function): Promise<any>; /** * Converts Markdown to HTML * @param {String} markdownString some Markdown * @param {Function} fn callback (optional) * @returns {Promise} HTML */ markdownToHtml(markdownString: string, fn: Function): Promise<any>; /** * Returns the number of minutes, hours, months elapsed for a time delta (milliseconds). * @param {Number} delta the time delta between two events, in milliseconds * @param {Function} fn callback (optional) * @returns {Promise} a string like "5m", "1h" */ approximately(delta: number, fn: Function): Promise<any>; /** * Generates a new set of access/secret keys. * Old keys are discarded and invalid after this. * @param {Function} fn callback (optional) * @returns {Promise} a map of new credentials */ newKeys(fn: Function): Promise<any>; /** * Returns all registered types for this App. * @param {Function} fn callback (optional) * @returns {Promise} a map of plural-singular form of all the registered types. */ types(fn: Function): Promise<any>; /** * Returns the number of objects for each existing type in this App. * @param {Function} fn callback (optional) * @returns {Promise} a map of singular object type to object count. */ typesCount(fn: Function): Promise<any>; /** * Returns a User or an App that is currently authenticated. * @param {String} accessToken a valid JWT access token (optional) * @param {Function} fn callback (optional) * @returns {Promise} a ParaObject */ me(accessToken: string, fn: Function): Promise<any>; /** * Upvote an object and register the vote in DB. * @param {ParaObject} obj the object to receive +1 votes * @param {String} voterid the userid of the voter * @param {Function} fn callback (optional) * @returns {Promise} true if vote was successful */ voteUp(obj: ParaObject, voterid: string, expiresAfter: any, lockedAfter: any, fn: Function): Promise<any>; /** * Downvote an object and register the vote in DB. * @param {ParaObject} obj the object to receive +1 votes * @param {String} voterid the userid of the voter * @param {Function} fn callback (optional) * @returns {Promise} true if vote was successful */ voteDown(obj: ParaObject, voterid: string, expiresAfter: any, lockedAfter: any, fn: Function): Promise<any>; /** * Rebuilds the entire search index. * @param {String} destinationIndex an existing index as destination * @param {Function} fn callback (optional) * @returns {Promise} a response object with properties "tookMillis" and "reindexed" */ rebuildIndex(destinationIndex: string, fn: Function): Promise<any>; /** * Returns the validation constraints map. * @param {String} type a type * @param {Function} fn callback (optional) * @returns {Promise} a map containing all validation constraints. */ validationConstraints(type: string, fn: Function): Promise<any>; /** * Add a new constraint for a given field. * @param {String} type a type * @param {String} field a field name * @param {Constraint} cons the constraint * @param {Function} fn callback (optional) * @returns {Promise} a map containing all validation constraints for this type. */ addValidationConstraint(type: string, field: string, cons: Constraint, fn: Function): Promise<any>; /** * Removes a validation constraint for a given field. * @param {String} type a type * @param {String} field a field name * @param {String} constraintName the name of the constraint to remove * @param {Function} fn callback (optional) * @returns {Promise} a map containing all validation constraints for this type. */ removeValidationConstraint(type: string, field: string, constraintName: string, fn: Function): Promise<any>; /** * Returns only the permissions for a given subject (user) of the current app. * If subject is not given returns the permissions for all subjects and resources for current app. * @param {String} subjectid the subject id (user id) * @param {Function} fn callback (optional) * @returns {Promise} a map of subject ids to resource names to a list of allowed methods */ resourcePermissions(subjectid: string, fn: Function): Promise<any>; /** * Grants a permission to a subject that allows them to call the specified HTTP methods on a given resource. * @param {String} subjectid subject id (user id) * @param {String} resourcePath resource path or object type * @param {Array} permission a set of HTTP methods * @param {Function} fn callback (optional) * @returns {Promise} a map of the permissions for this subject id */ grantResourcePermission(subjectid: string, resourcePath: string, permission: any[], fn: Function): Promise<any>; /** * Grants a permission to a subject that allows them to call the specified HTTP methods on a given resource. * @param {String} subjectid subject id (user id) * @param {String} resourcePath resource path or object type * @param {Array} permission a set of HTTP methods * @param {Boolean} allowGuestAccess if true - all unauthenticated requests will go through, 'false' by default. * @param {Function} fn callback (optional) * @returns {Promise} a map of the permissions for this subject id */ grantResourcePermissions(subjectid: string, resourcePath: string, permission: any[], allowGuestAccess: boolean, fn: Function): Promise<any>; /** * Revokes a permission for a subject, meaning they no longer will be able to access the given resource. * @param {String} subjectid subject id (user id) * @param {String} resourcePath resource path or object type * @param {Function} fn callback (optional) * @returns {Promise} a map of the permissions for this subject id */ revokeResourcePermission(subjectid: string, resourcePath: string, fn: Function): Promise<any>; /** * Revokes all permission for a subject. * @param {String} subjectid subject id (user id) * @param {Function} fn callback (optional) * @returns {Promise} a map of the permissions for this subject id */ revokeAllResourcePermissions(subjectid: string, fn: Function): Promise<any>; /** * Checks if a subject is allowed to call method X on resource Y. * @param {String} subjectid subject id * @param {String} resourcePath resource path or object type * @param {String} httpMethod HTTP method name * @param {Function} fn callback (optional) * @returns {Promise} true if allowed */ isAllowedTo(subjectid: string, resourcePath: string, httpMethod: string, fn: Function): Promise<any>; /** * Returns the value of a specific app setting (property) or all settings if key is blank. * @param {String} key a key * @param {Function} fn callback (optional) * @returns {Promise} a map */ appSettings(key: string, fn: Function): Promise<any>; /** * Adds or overwrites an app-specific setting. * @param {String} key a key * @param {Object} value a value * @param {Function} fn callback (optional) * @returns {Promise} void */ addAppSetting(key: string, value: any, fn: Function): Promise<any>; /** * Overwrites all app-specific settings. * @param {Object} settings a key-value map of properties * @param {Function} fn callback (optional) * @returns {Promise} void */ setAppSettings(settings: any, fn: Function): Promise<any>; /** * Removes an app-specific setting. * @param {String} key a key * @param {Function} fn callback (optional) * @returns {Promise} void */ removeAppSetting(key: string, fn: Function): Promise<any>; /** * Takes an identity provider access token and fetches the user data from that provider. * A new User object is created if that user doesn't exist. * Access tokens are returned upon successful authentication using one of the SDKs from * Facebook, Google, Twitter, etc. * Note: Twitter uses OAuth 1 and gives you a token and a token secret. * You must concatenate them like this: <code>{oauth_token}:{oauth_token_secret}</code> and * use that as the provider access token. * @param {String} provider identity provider, e.g. 'facebook', 'google'... * @param {String} providerToken access token from a provider like Facebook, Google, Twitter * @param {Boolean} rememberJWT if true, the access token returned by Para will be saved and available via getAccessToken() * @param {Function} fn callback (optional) * @returns {Promise} a User object or null if something failed */ signIn(provider: string, providerToken: string, rememberJWT: boolean, fn: Function): Promise<any>; /** * Clears the JWT access token but token is not revoked. * Tokens can be revoked globally per user with revokeAllTokens(). */ signOut(): void; /** * Refreshes the JWT access token. This requires a valid existing token. * Call link signIn() first. * @param {Function} fn callback (optional) * @returns {Promise} true if token was refreshed */ refreshToken(fn: Function): Promise<any>; /** * Revokes all user tokens for a given user id. * This would be equivalent to "logout everywhere". * Note: Generating a new API secret on the server will also invalidate all client tokens. * Requires a valid existing token. * @param {Function} fn callback (optional) * @returns {Promise} true if successful */ revokeAllTokens(fn: Function): Promise<any>; } import Pager from './Pager.js'; import ParaObject from './ParaObject.js'; import Constraint from './Constraint.js'; export { ParaObject, Pager, Constraint };