pryv 2.2.0 → 2.3.0

package/src/Service.js

@@ -1,25 +1,27 @@
-
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
 const utils = require('./utils.js');
 // Connection is required at the end of this file to allow circular requires.
 const Assets = require('./ServiceAssets.js');
 
-
 /**
- * @class Pryv.Service
+ * @class pryv.Service
  * A Pryv.io deployment is a unique "Service", as an example **Pryv Lab** is a service, deployed with the domain name **pryv.me**.
- * 
- * `Pryv.Service` exposes tools to interact with Pryv.io at a "Platform" level. 
+ *
+ * `pryv.Service` exposes tools to interact with Pryv.io at a "Platform" level.
  *
  *  ##### Initizalization with a service info URL
-```javascript
-const service = new Pryv.Service('https://reg.pryv.me/service/info');
+```js
+const service = new pryv.Service('https://reg.pryv.me/service/info');
 ```
 
 - With the content of a serviceInfo configuration
 
 Service information properties can be overriden with specific values. This might be usefull to test new designs on production platforms.
 
-```javascript
+```js
 const serviceInfoUrl = 'https://reg.pryv.me/service/info';
 const serviceCustomizations = {
   name: 'Pryv Lab 2',
@@ -27,68 +29,67 @@ const serviceCustomizations = {
     definitions: 'https://pryv.github.io/assets-pryv.me/index.json'
   }
 }
-const service = new Pryv.Service(serviceInfoUrl, serviceCustomizations);
-``` 
+const service = new pryv.Service(serviceInfoUrl, serviceCustomizations);
+```
 
- * @memberof Pryv
- * 
+ * @memberof pryv
+ *
  * @constructor
  * @param {string} serviceInfoUrl Url point to /service/info of a Pryv platform see: {@link https://api.pryv.com/reference/#service-info}
  */
 class Service {
-
   constructor (serviceInfoUrl, serviceCustomizations) {
-    this._pryvServiceInfo = null;
+    this._serviceInfo = null;
     this._assets = null;
     this._polling = false;
-    this._pryvServiceInfoUrl = serviceInfoUrl;
+    this._serviceInfoUrl = serviceInfoUrl;
     this._pryvServiceCustomizations = serviceCustomizations;
   }
 
   /**
    * Return service info parameters info known of fetch it if needed.
-   * Example   
-   *  - name of a platform   
-   *    `const serviceName = await service.info().name` 
-   * @see PryvServiceInfo For details on available properties.
+   * Example
+   *  - name of a platform
+   *    `const serviceName = await service.info().name`
+   * @see ServiceInfo For details on available properties.
    * @param {boolean?} forceFetch If true, will force fetching service info.
-   * @returns {Promise<PryvServiceInfo>} Promise to Service info Object
+   * @returns {Promise<ServiceInfo>} Promise to Service info Object
    */
   async info (forceFetch) {
-    if (forceFetch || !this._pryvServiceInfo) {
+    if (forceFetch || !this._serviceInfo) {
       let baseServiceInfo = {};
-      if (this._pryvServiceInfoUrl) {
-        const res = await utils.superagent.get(this._pryvServiceInfoUrl).set('Access-Control-Allow-Origin', '*').set('accept', 'json');
+      if (this._serviceInfoUrl) {
+        const res = await utils.superagent.get(this._serviceInfoUrl).set('Access-Control-Allow-Origin', '*').set('accept', 'json');
         baseServiceInfo = res.body;
       }
       Object.assign(baseServiceInfo, this._pryvServiceCustomizations);
       this.setServiceInfo(baseServiceInfo);
     }
-    return this._pryvServiceInfo;
+    return this._serviceInfo;
   }
 
   /**
    * @private
-   * @param {PryvServiceInfo} serviceInfo
+   * @param {ServiceInfo} serviceInfo
    */
   setServiceInfo (serviceInfo) {
     if (!serviceInfo.name) {
       throw new Error('Invalid data from service/info');
     }
-    // cleanup serviceInfo for eventual url not finishing by "/" 
+    // cleanup serviceInfo for eventual url not finishing by "/"
     // code will be obsolete with next version of register
     ['access', 'api', 'register'].forEach((key) => {
       if (serviceInfo[key].slice(-1) !== '/') {
         serviceInfo[key] += '/';
       }
     });
-    this._pryvServiceInfo = serviceInfo;
+    this._serviceInfo = serviceInfo;
   }
 
   /**
    * Return assets property content
    * @param {boolean?} forceFetch If true, will force fetching service info.
-   * @returns {Promise<ServiceAssets>} Promise to ServiceAssets 
+   * @returns {Promise<ServiceAssets>} Promise to ServiceAssets
    */
   async assets (forceFetch) {
     if (!forceFetch && this._assets) {
@@ -106,17 +107,17 @@ class Service {
 
   /**
    * Return service info parameters info known or null if not yet loaded
-   * @returns {PryvServiceInfo} Service Info definition
+   * @returns {ServiceInfo} Service Info definition
    */
   infoSync () {
-    return this._pryvServiceInfo;
+    return this._serviceInfo;
   }
 
   /**
    * Return an API Endpoint from a username and token
    * @param {string} username
    * @param {string} [token]
-   * @return {PryvApiEndpoint}
+   * @return {APIEndpoint}
    */
   async apiEndpointFor (username, token) {
     const serviceInfo = await this.info();
@@ -124,25 +125,25 @@ class Service {
   }
 
   /**
-   * Return an API Endpoint from a username and token and a PryvServiceInfo. 
+   * Return an API Endpoint from a username and token and a ServiceInfo.
    * This is method is rarely used. See **apiEndpointFor** as an alternative.
-   * @param {PryvServiceInfo} serviceInfo
+   * @param {ServiceInfo} serviceInfo
    * @param {string} username
    * @param {string} [token]
-   * @return {PryvApiEndpoint}
+   * @return {APIEndpoint}
    */
   static buildAPIEndpoint (serviceInfo, username, token) {
     const endpoint = serviceInfo.api.replace('{username}', username);
-    return utils.buildPryvApiEndpoint({ endpoint: endpoint, token: token });
+    return utils.buildAPIEndpoint({ endpoint: endpoint, token: token });
   }
 
   /**
-   * Issue a "login call on the Service" return a Connection on success  
+   * Issue a "login call on the Service" return a Connection on success
    * **! Warning**: the token of the connection will be a "Personal" token that expires
    * @see https://api.pryv.com/reference-full/#login-user
-   * @param {string} username 
-   * @param {string} password 
-   * @param {string} appId 
+   * @param {string} username
+   * @param {string} password
+   * @param {string} appId
    * @param {string} [originHeader=service-info.register] Only for Node.js. If not set will use the register value of service info. In browsers this will overridden by current page location.
    * @throws {Error} on invalid login
    */
@@ -167,10 +168,11 @@ class Service {
         this // Pre load Connection with service
       );
     } catch (e) {
-      if (e.response && e.response.body
-        && e.response.body.error
-        && e.response.body.error.message) {
-        throw new Error(e.response.body.error.message)
+      if (e.response &&
+          e.response.body &&
+          e.response.body.error &&
+          e.response.body.error.message) {
+        throw new Error(e.response.body.error.message);
       }
     }
   }
@@ -183,7 +185,7 @@ const Connection = require('./Connection');
 
 /**
  * Object to handle Pryv Service Informations https://api.pryv.com/reference/#service-info
- * @typedef {Object} PryvServiceInfo
+ * @typedef {Object} ServiceInfo
  * @property {string} register The URL of the register service.
  * @property {string} access The URL of the access page.
  * @property {string} api The API endpoint format.
@@ -191,7 +193,7 @@ const Connection = require('./Connection');
  * @property {string} home The URL of the platform's home page.
  * @property {string} support The email or URL of the support page.
  * @property {string} terms The terms and conditions, in plain text or the URL displaying them.
- * @property {string} eventTypes The URL of the list of validated event types.
+ * @property {string} eventTypes The URL of the list of validated event types.
  * @property {Object} [assets] Holder for service specific Assets (icons, css, ...)
  * @property {String} [assets.definitions] URL to json object with assets definitions
  */

package/src/ServiceAssets.js

@@ -1,10 +1,17 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
 const utils = require('./utils.js');
+
+/* global location */
+
 /**
  * Holds Pryv Service informations.
- * 
+ *
  * It's returned by `service.assets()`
  *
- * @memberof Pryv
+ * @memberof pryv
  **/
 class ServiceAssets {
   /**
@@ -12,7 +19,7 @@ class ServiceAssets {
    * @param { object} assets The content of service/info.assets properties.
    * @param { string } pryvServiceAssetsSourceUrl Url point to assets of the service of a Pryv platform: https://api.pryv.com/reference/#service-info property `assets.src`
    */
-  constructor(assets, assetsURL) {
+  constructor (assets, assetsURL) {
     this._assets = assets;
     this._assetsURL = assetsURL;
   }
@@ -22,7 +29,7 @@ class ServiceAssets {
    * @param {string} pryvServiceAssetsSourceUrl
    * @returns {ServiceAssets}
    */
-  static async setup(pryvServiceAssetsSourceUrl) {
+  static async setup (pryvServiceAssetsSourceUrl) {
     const res = await utils.superagent.get(pryvServiceAssetsSourceUrl).set('accept', 'json');
     return new ServiceAssets(res.body, pryvServiceAssetsSourceUrl);
   }
@@ -30,9 +37,9 @@ class ServiceAssets {
   /**
    * get a value from path separated by `:`
    * exemple of key `lib-js:buttonSignIn`
-   * @param {string} [keyPath] if null, will return the all assets  
+   * @param {string} [keyPath] if null, will return the all assets
    */
-  get(keyPath) {
+  get (keyPath) {
     let result = Object.assign({}, this._assets);
     if (keyPath) {
       keyPath.split(':').forEach((key) => {
@@ -47,12 +54,12 @@ class ServiceAssets {
    * get an Url from path separated by `:`
    * identical to doing assets.relativeURL(assets.get(keyPath))
    * exemple of key `lib-js:buttonSignIn`
-   * @param {string} [keyPath] if null, will return the all assets  
+   * @param {string} [keyPath] if null, will return the all assets
    */
-  getUrl(keyPath) {
+  getUrl (keyPath) {
     const url = this.get(keyPath);
     if (typeof url !== 'string') {
-      throw new Error(url + ' returned ' + value); 
+      throw new Error(`Unexpected value for ${keyPath}: ${url}`);
     }
     return this.relativeURL(url);
   }
@@ -60,16 +67,16 @@ class ServiceAssets {
   /**
    * get relativeUrl
    */
-  relativeURL(url) {
+  relativeURL (url) {
     return relPathToAbs(this._assets.baseUrl || this._assetsURL, url);
   }
 
-  //----------------   Default service ressources
-  
+  // ---------------- Default service resources
+
   /**
    * Set all defaults Favicon, CSS
    */
-  async setAllDefaults() {
+  async setAllDefaults () {
     this.setFavicon();
     await this.loadCSS();
   }
@@ -77,8 +84,8 @@ class ServiceAssets {
   /**
    * Set service Favicon to Web Page
    */
-  setFavicon() {
-    var link = document.querySelector("link[rel*='icon']") || document.createElement('link');
+  setFavicon () {
+    const link = document.querySelector("link[rel*='icon']") || document.createElement('link');
     link.type = 'image/x-icon';
     link.rel = 'shortcut icon';
     link.href = this.relativeURL(this._assets.favicon.default.url);
@@ -88,40 +95,41 @@ class ServiceAssets {
   /**
    * Set default service CSS
    */
-  async loadCSS() {
+  async loadCSS () {
     loadCSS(this.relativeURL(this._assets.css.default.url));
   }
 
   // ---- Login
 
   /**
-  * Load CSS for Login button
-  */
+   * Load CSS for Login button
+   */
   async loginButtonLoadCSS () {
     loadCSS(this.relativeURL(this._assets['lib-js'].buttonSignIn.css));
   }
 
   /**
-  * Get HTML for Login Button
-  */
-  async loginButtonGetHTML() {
+   * Get HTML for Login Button
+   */
+  async loginButtonGetHTML () {
     const res = await utils.superagent.get(this.relativeURL(this._assets['lib-js'].buttonSignIn.html)).set('accept', 'html');
     return res.text;
   }
 
- /**
- * Get Messages strings for Login Button
- */
-  async loginButtonGetMessages() {
+  /**
+   * Get Messages strings for Login Button
+   */
+  async loginButtonGetMessages () {
     const res = await utils.superagent.get(this.relativeURL(this._assets['lib-js'].buttonSignIn.messages)).set('accept', 'json');
     return res.body;
   }
-
 }
 
-function loadCSS(url) {
-  var head = document.getElementsByTagName('head')[0];
-  var link = document.createElement('link');
+module.exports = ServiceAssets;
+
+function loadCSS (url) {
+  const head = document.getElementsByTagName('head')[0];
+  const link = document.createElement('link');
   link.id = url;
   link.rel = 'stylesheet';
   link.type = 'text/css';
@@ -130,8 +138,11 @@ function loadCSS(url) {
   head.appendChild(link);
 }
 
+/* HACK: disabling linting until code is cleaned up */
+/* eslint-disable */
+
   /*\
-  |*| Modified version of 
+  |*| Modified version of
   |*| :: translate relative paths to absolute paths ::
   |*|
   |*| https://developer.mozilla.org/en-US/docs/Web/API/document.cookie
@@ -154,9 +165,6 @@ function relPathToAbs (baseUrlString, sRelPath) {
     sDir = (sDir + sPath.substring(nStart, nEnd)).replace(new RegExp("(?:\\\/+[^\\\/]*){0," + ((nUpLn - 1) / 3) + "}$"),
       "/");
   }
-  let portStr = baseLocation.port ? ':' + baseLocation.port : '';
+  const portStr = baseLocation.port ? ':' + baseLocation.port : '';
   return baseLocation.protocol + '//' + baseLocation.hostname + portStr + sDir + sPath.substr(nStart);
 }
-
-
-module.exports = ServiceAssets;

package/src/browser-index-bundle.js

@@ -0,0 +1,8 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+const pryv = require('./browser-index');
+require('@pryv/socket.io')(pryv);
+require('@pryv/monitor')(pryv);
+module.exports = pryv;

package/src/browser-index.js

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+// make lib available as `Pryv` (with capital P, deprecated) for backward-compatibility with apps importing via <script>
+// TODO: remove deprecated alias with next major version
+module.exports = global.Pryv = require('./index');

package/src/index.d.ts

@@ -168,7 +168,7 @@ declare module 'pryv' {
 
   type EditMetadata = 'created' | 'createdBy' | 'modified' | 'modifiedBy';
 
-  export type ApiCallMethods = {
+  export type APICallMethods = {
     // mfa
     'mfa.challenge': {
       params: null;
@@ -516,20 +516,20 @@ declare module 'pryv' {
   ) extends (k: infer I) => any
     ? I
     : never;
-  type ApiCallResultUnion = ApiCallMethods[keyof ApiCallMethods]['res'];
-  type ApiCallResultTypes = UnionToIntersection<
-    NonNullable<ApiCallResultUnion>
+  type APICallResultUnion = APICallMethods[keyof APICallMethods]['res'];
+  type APICallResultTypes = UnionToIntersection<
+    NonNullable<APICallResultUnion>
   >;
 
   type PossibleError = {
     error?: Error;
   };
 
-  type ApiCallResult<K extends keyof ApiCallMethods> =
-    ApiCallMethods[K]['res'] & PossibleError;
+  type APICallResult<K extends keyof APICallMethods> =
+    APICallMethods[K]['res'] & PossibleError;
 
-  export type ApiCallResultHandler<K extends keyof ApiCallMethods> = (
-    result: ApiCallResult<K>,
+  export type APICallResultHandler<K extends keyof APICallMethods> = (
+    result: APICallResult<K>,
   ) => Promise<any>;
   export type StreamedEventsHandler = (event: Event) => void;
 
@@ -546,36 +546,36 @@ declare module 'pryv' {
   export type EventFileCreationParams = Partial<
     Omit<Event, 'attachments' | EditMetadata>
   >;
-  export type ApiCall<K extends keyof ApiCallMethods = keyof ApiCallMethods> =
-    K extends keyof ApiCallMethods
+  export type APICall<K extends keyof APICallMethods = keyof APICallMethods> =
+    K extends keyof APICallMethods
       ? {
           method: K;
-          params: ApiCallMethods[K]['params'];
-          handleResult?: ApiCallResultHandler<K>;
+          params: APICallMethods[K]['params'];
+          handleResult?: APICallResultHandler<K>;
         }
       : never;
 
-  export type TypedApiCallResult = ApiCallResultTypes & PossibleError;
+  export type TypedAPICallResult = APICallResultTypes & PossibleError;
 
-  export type ApiCallProgressHandler = (percentage: number) => void;
+  export type APICallProgressHandler = (percentage: number) => void;
 
   interface AccessInfo extends Access {
     calls: KeyValue;
     user: KeyValue;
   }
 
-  type EventApiCallRes = {
+  type EventAPICallRes = {
     event?: Event;
   } & PossibleError;
 
   export interface Connection {
-    new (pryvApiEndpoint: string, service?: Service): Connection;
+    new (apiEndpoint: string, service?: Service): Connection;
     get service(): Service;
     username(): Promise<string>;
-    api<Calls extends ApiCall[] = ApiCall[]>(
+    api<Calls extends APICall[] = APICall[]>(
       apiCalls: Calls,
-      res?: ApiCallProgressHandler[],
-    ): Promise<Array<TypedApiCallResult>>;
+      res?: APICallProgressHandler[],
+    ): Promise<Array<TypedAPICallResult>>;
     getEventsStreamed(
       queryParams: Partial<EventQueryParamsStreamQuery>,
       forEachEvent: StreamedEventsHandler,
@@ -583,16 +583,16 @@ declare module 'pryv' {
     createEventWithFile(
       params: EventFileCreationParams,
       filePath: string | Buffer | Blob,
-    ): Promise<EventApiCallRes>;
+    ): Promise<EventAPICallRes>;
     createEventWithFormData(
       params: EventFileCreationParams,
       formData: FormData,
-    ): Promise<EventApiCallRes>;
+    ): Promise<EventAPICallRes>;
     createEventWithFileFromBuffer(
       params: EventFileCreationParams,
-      bufferData: string | Buffer,
+      bufferData: string | Buffer | Blob,
       filename: string,
-    ): Promise<EventApiCallRes>;
+    ): Promise<EventAPICallRes>;
     addPointsToHFEvent(
       id: Identifier,
       fields: string[],
@@ -615,7 +615,7 @@ declare module 'pryv' {
     };
   };
 
-  export type PryvServiceInfo = {
+  export type ServiceInfo = {
     register: string;
     access: string;
     api: string;
@@ -625,6 +625,10 @@ declare module 'pryv' {
     terms: string;
     eventTypes: string;
     version: string;
+    assets: {
+      definitions: string;
+    };
+    serial: string;
   };
 
   export type AssetsConfig = {
@@ -650,10 +654,10 @@ declare module 'pryv' {
       serviceInfoUrl: string,
       serviceCustomizations?: serviceCustomizations,
     ): Service;
-    info(forceFetch?: boolean): Promise<PryvServiceInfo>;
-    setServiceInfo(serviceInfo: Partial<PryvServiceInfo>): Promise<void>;
+    info(forceFetch?: boolean): Promise<ServiceInfo>;
+    setServiceInfo(serviceInfo: Partial<ServiceInfo>): Promise<void>;
     assets(forceFetch?: boolean): Promise<AssetsConfig>;
-    infoSync(): PryvServiceInfo | null;
+    infoSync(): ServiceInfo | null;
     apiEndpointFor(username: string, token: string): Promise<string>;
     login(
       username: string,
@@ -676,22 +680,6 @@ declare module 'pryv' {
     | 'ACCEPTED'
     | 'SIGNOUT';
 
-  type ServiceInfo = {
-    access: string;
-    api: string;
-    assets: {
-      definitions: string;
-    };
-    eventTypes: string;
-    home: string;
-    name: string;
-    register: string;
-    serial: string;
-    support: string;
-    terms: string;
-    version: string;
-  };
-
   type StateChangeTypes = {
     LOADING: {};
     INITIALIZED: {
@@ -816,15 +804,15 @@ declare module 'pryv' {
     serviceInfoFromUrl: getServiceInfoFromURL;
   }
 
-  type TokenAndApiEndpoint = {
+  type TokenAndAPIEndpoint = {
     endpoint: string;
     token: string;
   };
 
   export interface utils {
     isBrowser(): boolean;
-    extractTokenAndApiEndpoint(pryvApiEndpoint: string): TokenAndApiEndpoint;
-    buildPryvApiEndpoint(tokenAndApi: TokenAndApiEndpoint): string;
+    extractTokenAndAPIEndpoint(apiEndpoint: string): TokenAndAPIEndpoint;
+    buildAPIEndpoint(tokenAndAPI: TokenAndAPIEndpoint): string;
     browserIsMobileOrTablet(navigator: string): boolean;
     cleanURLFromPrYvParams(url: string): string;
     getQueryParamsFromURL(url: string): KeyValue;
@@ -832,7 +820,7 @@ declare module 'pryv' {
 
   type version = string;
 
-  let Pryv: {
+  let pryv: {
     Service: Service;
     Connection: Connection;
     Auth: Auth;
@@ -841,5 +829,5 @@ declare module 'pryv' {
     version: version;
   };
 
-  export default Pryv;
+  export default pryv;
 }

package/src/index.js

@@ -1,3 +1,20 @@
-const Pryv = require('./Pryv');
-
-module.exports = Pryv;
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+/**
+ * `pryv` library
+ * @exports pryv
+ * @property {pryv.Service} Service - To interact with Pryv.io at a "Platform level"
+ * @property {pryv.Connection} Connection - To interact with an individual's (user) data set
+ * @property {pryv.Browser} Browser - Browser Tools - Access request helpers and visuals (button)
+ * @property {pryv.utils} utils - Exposes **superagent** for HTTP calls and tools to manipulate Pryv's API Endpoints
+ */
+module.exports = {
+  Service: require('./Service'),
+  Connection: require('./Connection'),
+  Auth: require('./Auth'),
+  Browser: require('./Browser'),
+  utils: require('./utils'),
+  version: require('../package.json').version
+};