pryv 2.4.6 → 3.0.0

package/src/Connection.js

@@ -4,7 +4,8 @@
  */
 const utils = require('./utils.js');
 const jsonParser = require('./lib/json-parser');
-const browserGetEventStreamed = require('./lib/browser-getEventStreamed');
+const libGetEventStreamed = require('./lib/getEventStreamed');
+const PryvError = require('./lib/PryvError');
 
 /**
  * @class Connection
@@ -51,19 +52,26 @@ class Connection {
   }
 
   /**
-   * get username.
-   * It's async as in it constructed from access info
-   * @param {*} arrayOfAPICalls
-   * @param {*} progress
+   * Get username for this connection.
+   * It's async as it's constructed from access info.
+   * @returns {Promise<string>} Promise resolving to the username
    */
   async username () {
     const accessInfo = await this.accessInfo();
+    if (accessInfo.error) {
+      throw new PryvError(
+        'Failed fetching accessinfo: ' + accessInfo.error.message,
+        accessInfo.error
+      );
+    }
+    // @ts-ignore - username is always a string
     return accessInfo.user.username;
   }
 
   /**
-   * get access info
-   * It's async as it is constructed with get function.
+   * Get access info for this connection.
+   * It's async as it is fetched from the API.
+   * @returns {Promise<AccessInfo>} Promise resolving to the access info
    */
   async accessInfo () {
     return this.get('access-info', null);
@@ -89,11 +97,12 @@ class Connection {
   }
 
   /**
-   * Make one api Api call
-   * @param {string} method - methodId
-   * @param {Object|Array} [params] - the params associated with this methodId
-   * @param {string} [resultKey] - if given, returns the value or throws an error if not present
-   * @throws {Error} if .error is present the response
+   * Make one API call
+   * @param {string} method - Method ID (e.g., 'events.get', 'streams.create')
+   * @param {Object|Array} [params={}] - The params associated with this method
+   * @param {string} [expectedKey] - If given, returns the value of this key or throws an error if not present
+   * @returns {Promise<Object>} Promise resolving to the API result or the value of expectedKey
+   * @throws {Error} If .error is present in the response or expectedKey is missing
    */
   async apiOne (method, params = {}, expectedKey) {
     const result = await this.api([{ method, params }]);
@@ -103,13 +112,12 @@ class Connection {
       (expectedKey != null && result[0][expectedKey] == null)
     ) {
       const innerObject = result[0]?.error || result;
-      const error = new Error(
+      throw new PryvError(
         `Error for api method: "${method}" with params: ${JSON.stringify(
           params
-        )} >> Result: ${JSON.stringify(innerObject)}"`
+        )} >> Result: ${JSON.stringify(innerObject)}"`,
+        innerObject
       );
-      error.innerObject = innerObject;
-      throw error;
     }
     if (expectedKey != null) return result[0][expectedKey];
     return result[0];
@@ -117,9 +125,10 @@ class Connection {
 
   /**
    * Revoke : Delete the accessId
-   * - Do not thow error if access is already revoked, just return null;
-   * @param {boolean} [throwOnFail = true] - if set to false do not throw Error on failure
-   * @param {Connection} [usingConnection] - specify which connection issues the revoke, might be necessary when selfRovke
+   * - Do not throw error if access is already revoked, just return null;
+   * @param {boolean} [throwOnFail=true] - if set to false do not throw Error on failure
+   * @param {Connection} [usingConnection] - specify which connection issues the revoke, might be necessary when selfRevoke
+   * @returns {Promise<Object|null>} Promise resolving to deletion result or null if already revoked/failed
    */
   async revoke (throwOnFail = true, usingConnection) {
     usingConnection = usingConnection || this;
@@ -174,7 +183,6 @@ class Connection {
         });
       }
       const resRequest = await callHandler(thisBatch);
-
       // result checks
       if (!resRequest || !Array.isArray(resRequest.results)) {
         throw new Error(
@@ -193,7 +201,8 @@ class Connection {
         if (arrayOfAPICalls[i + cursor].handleResult) {
           await arrayOfAPICalls[i + cursor].handleResult.call(
             null,
-            resRequest.results[i]
+            resRequest.results[i],
+            thisBatch[i] // request
           );
         }
       }
@@ -207,76 +216,107 @@ class Connection {
   }
 
   /**
-   * Post to API return results
-   * @param {(Array | Object)} data
-   * @param {Object} queryParams
-   * @param {string} path
-   * @returns {Promise<Array|Object>} Promise to result.body
+   * Post to API and return results
+   * @param {string} path - API path
+   * @param {(Array | Object)} data - Data to post
+   * @returns {Promise<Object|Object[]>} Promise to result.body
    */
-  async post (path, data, queryParams) {
+  async post (path, data) {
     const now = getTimestamp();
-    const res = await this.postRaw(path, data, queryParams);
+    const res = await this._postFetch(path, data);
     this._handleMeta(res.body, now);
     return res.body;
   }
 
   /**
-   * Raw Post to API return superagent object
-   * @param {Array | Object} data
-   * @param {Object} queryParams
-   * @param {string} path
-   * @returns {request.superagent}  Promise from superagent's post request
+   * @private
+   * Post object as JSON to API
+   * @param {string} path - API path
+   * @param {Array | Object} data - Data to post as JSON
+   * @returns {Promise<{response: Response, body: Object|Object[]}>} Promise to response and body
    */
-  async postRaw (path, data, queryParams) {
-    return this._post(path).query(queryParams).send(data);
+  async _postFetch (path, data) {
+    return this._postFetchRaw(path, JSON.stringify(data), 'application/json');
   }
 
-  _post (path) {
-    return utils.superagent
-      .post(this.endpoint + path)
-      .set('Authorization', this.token)
-      .set('accept', 'json');
+  /**
+   * @private
+   * Raw Post to API
+   * @param {string} path - API path
+   * @param {any} data - Raw data to post
+   * @param {string} [contentType] - Content-Type header (optional, allows fetch to set it for FormData)
+   * @returns {Promise<{response: Response, body: Object|Object[]}>} Promise to response and body
+   */
+  async _postFetchRaw (path, data, contentType) {
+    const headers = {
+      Authorization: this.token,
+      Accept: 'application/json'
+    };
+    // optional for form-data llowing fetch to
+    // automatically set multipart/form-data with the correct boundary
+    if (contentType) {
+      headers['Content-Type'] = contentType;
+    }
+    const response = await fetch(this.endpoint + path, {
+      method: 'POST',
+      headers,
+      body: data
+    });
+    const body = await response.json();
+    return { response, body };
   }
 
   /**
-   * Post to API return results
-   * @param {Object} queryParams
-   * @param {string} path
-   * @returns {Promise<Array|Object>}  Promise to result.body
+   * GET from API and return results
+   * @param {string} path - API path
+   * @param {Object} [queryParams] - Query parameters
+   * @returns {Promise<Object|Object[]>} Promise to result.body
    */
   async get (path, queryParams) {
     const now = getTimestamp();
-    const res = await this.getRaw(path, queryParams);
+    const res = await this._getFetchRaw(path, queryParams);
     this._handleMeta(res.body, now);
     return res.body;
   }
 
   /**
-   * Raw Get to API return superagent object
-   * @param {Object} queryParams
-   * @param {string} path
-   * @returns {request.superagent}  Promise from superagent's get request
+   * @private
+   * Raw GET from API
+   * @param {string} path - API path
+   * @param {Object} [queryParams={}] - Query parameters
+   * @returns {Promise<{response: Response, body: Object|Object[]}>} Promise to response and body
    */
-  getRaw (path, queryParams) {
+  async _getFetchRaw (path, queryParams = {}) {
     path = path || '';
-    return utils.superagent
-      .get(this.endpoint + path)
-      .set('Authorization', this.token)
-      .set('accept', 'json')
-      .query(queryParams);
+    let queryStr = '';
+    if (queryParams && Object.keys(queryParams).length > 0) {
+      queryStr = '?' + new URLSearchParams(queryParams).toString();
+    }
+    const response = await fetch(this.endpoint + path + queryStr, {
+      headers: {
+        Authorization: this.token,
+        Accept: 'application/json'
+      }
+    });
+    const body = await response.json();
+    return { response, body };
   }
 
   /**
-   * ADD Data Points to HFEvent (flatJSON format)
-   * https://api.pryv.com/reference/#add-hf-series-data-points
+   * Add data points to an HF (High Frequency) series event (flatJSON format)
+   * @param {string} eventId - The HF event ID
+   * @param {string[]} fields - Array of field names for the series
+   * @param {Array<Array<number|string>>} points - Array of data points, each point is an array of values
+   * @returns {Promise<HFSeriesAddResult>} Promise resolving to status response
+   * @see https://api.pryv.com/reference/#add-hf-series-data-points
    */
   async addPointsToHFEvent (eventId, fields, points) {
     const res = await this.post('events/' + eventId + '/series', {
       format: 'flatJSON',
-      fields: fields,
-      points: points
+      fields,
+      points
     });
-    if (!res.status === 'ok') {
+    if (res.status !== 'ok') {
       throw new Error('Failed loading serie: ' + JSON.stringify(res.status));
     }
     return res;
@@ -284,7 +324,6 @@ class Connection {
 
   /**
    * Streamed get Event.
-   * Fallbacks to not streamed, for browsers that does not support `fetch()` API
    * @see https://api.pryv.com/reference/#get-events
    * @param {Object} queryParams See `events.get` parameters
    * @param {Function} forEachEvent Function taking one event as parameter. Will be called for each event
@@ -292,38 +331,7 @@ class Connection {
    */
   async getEventsStreamed (queryParams, forEachEvent) {
     const myParser = jsonParser(forEachEvent, queryParams.includeDeletions);
-    let res = null;
-    if (typeof window === 'undefined') {
-      // node
-      res = await this.getRaw('events', queryParams)
-        .buffer(false)
-        .parse(myParser);
-    } else if (
-      typeof fetch !== 'undefined' &&
-      !(typeof navigator !== 'undefined' && navigator.product === 'ReactNative')
-    ) {
-      // browser supports fetch and it is not react native
-      res = await browserGetEventStreamed(this, queryParams, myParser);
-    } else {
-      // browser no fetch supports
-      console.log(
-        'WARNING: Browser does not support fetch() required by pryv.Connection.getEventsStreamed()'
-      );
-      res = await this.getRaw('events', queryParams);
-      res.body.eventsCount = 0;
-      if (res.body.events) {
-        res.body.events.forEach(forEachEvent);
-        res.body.eventsCount += res.body.events.length;
-        delete res.body.events;
-      }
-      if (res.body.eventDeletions) {
-        // deletions are in a seprated Array
-        res.body.eventDeletions.forEach(forEachEvent);
-        res.body.eventsCount += res.body.eventDeletions.length;
-        delete res.body.eventDeletions;
-      }
-    }
-
+    const res = await libGetEventStreamed(this, queryParams, myParser);
     const now = getTimestamp();
     this._handleMeta(res.body, now);
     return res.body;
@@ -336,38 +344,44 @@ class Connection {
    * @param {string} filePath
    */
   async createEventWithFile (event, filePath) {
-    const res = await this._post('events')
-      .field('event', JSON.stringify(event))
-      .attach('file', filePath);
+    const fs = require('fs');
+    const path = require('path');
+
+    if (!fs || !path) {
+      throw new Error('createEventWithFile is only available in Node.js. Use createEventWithFormData in browser.');
+    }
+
+    const fileName = path.basename(filePath);
+    const mimeType = getMimeType(path.extname(filePath));
+    const fileBlob = await fs.openAsBlob(filePath, { type: mimeType });
+
+    const formData = new FormData();
+    formData.append('event', JSON.stringify(event));
+    formData.append('file', fileBlob, fileName);
 
     const now = getTimestamp();
-    this._handleMeta(res.body, now);
-    return res.body;
+    const { body } = await this._postFetchRaw('events', formData);
+    this._handleMeta(body, now);
+    return body;
   }
 
   /**
    * Create an event from a Buffer
-   * @param {Event} event
+   * @param {Object} event
    * @param {Buffer|Blob} bufferData - Buffer for node, Blob for browser
-   * @param {string} fileName
+   * @param {string} filename
    */
   async createEventWithFileFromBuffer (event, bufferData, filename) {
-    if (typeof window === 'undefined') {
-      // node
-      const res = await this._post('events')
-        .field('event', JSON.stringify(event))
-        .attach('file', bufferData, filename);
-
-      const now = getTimestamp();
-      this._handleMeta(res.body, now);
-      return res.body;
-    } else {
-      /* global FormData */
-      const formData = new FormData();
-      formData.append('file', bufferData, filename);
-      const body = await this.createEventWithFormData(event, formData);
-      return body;
-    }
+    const mimeType = getMimeType(getExtname(filename));
+    const fileBlob = bufferData instanceof Blob
+      ? bufferData
+      // @ts-ignore - Buffer is valid for Blob in Node.js
+      : new Blob([bufferData], { type: mimeType });
+
+    const formData = new FormData();
+    formData.append('file', fileBlob, filename);
+    const body = await this.createEventWithFormData(event, formData);
+    return body;
   }
 
   /**
@@ -378,8 +392,8 @@ class Connection {
    */
   async createEventWithFormData (event, formData) {
     formData.append('event', JSON.stringify(event));
-    const res = await this._post('events').send(formData);
-    return res.body;
+    const { body } = await this._postFetchRaw('events', formData);
+    return body;
   }
 
   /**
@@ -393,9 +407,9 @@ class Connection {
   }
 
   /**
-   * API endpoint of this connection
+   * API endpoint of this connection (includes token if present)
    * @readonly
-   * @property {APIEndpoint} deltaTime
+   * @property {APIEndpoint} apiEndpoint
    */
   get apiEndpoint () {
     return utils.buildAPIEndpoint(this);
@@ -421,6 +435,45 @@ function getTimestamp () {
   return Date.now() / 1000;
 }
 
+const MIME_TYPES = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.svg': 'image/svg+xml',
+  '.bmp': 'image/bmp',
+  '.ico': 'image/x-icon',
+  '.pdf': 'application/pdf',
+  '.json': 'application/json',
+  '.xml': 'application/xml',
+  '.zip': 'application/zip',
+  '.gz': 'application/gzip',
+  '.tar': 'application/x-tar',
+  '.txt': 'text/plain',
+  '.html': 'text/html',
+  '.htm': 'text/html',
+  '.css': 'text/css',
+  '.js': 'application/javascript',
+  '.mjs': 'application/javascript',
+  '.mp3': 'audio/mpeg',
+  '.wav': 'audio/wav',
+  '.ogg': 'audio/ogg',
+  '.mp4': 'video/mp4',
+  '.webm': 'video/webm',
+  '.avi': 'video/x-msvideo',
+  '.mov': 'video/quicktime'
+};
+
+function getMimeType (ext) {
+  return MIME_TYPES[ext.toLowerCase()] || 'application/octet-stream';
+}
+
+function getExtname (filename) {
+  const lastDot = filename.lastIndexOf('.');
+  return lastDot >= 0 ? filename.slice(lastDot) : '';
+}
+
 // service is require "after" to allow circular require
 const Service = require('./Service');
 

package/src/Service.js

@@ -52,17 +52,18 @@ class Service {
    *  - 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.
+   * @param {boolean} [forceFetch] If true, will force fetching service info.
    * @returns {Promise<ServiceInfo>} Promise to Service info Object
    */
   async info (forceFetch) {
     if (forceFetch || !this._serviceInfo) {
       let baseServiceInfo = {};
       if (this._serviceInfoUrl) {
-        const res = await utils.superagent.get(this._serviceInfoUrl).set('Access-Control-Allow-Origin', '*').set('accept', 'json');
-        baseServiceInfo = res.body;
+        const { body } = await utils.fetchGet(this._serviceInfoUrl);
+        baseServiceInfo = body;
       }
       Object.assign(baseServiceInfo, this._pryvServiceCustomizations);
+      // @ts-ignore - baseServiceInfo is populated from body or customizations
       this.setServiceInfo(baseServiceInfo);
     }
     return this._serviceInfo;
@@ -70,7 +71,7 @@ class Service {
 
   /**
    * Check if a service supports High Frequency Data Sets
-   * @return true if yes
+   * @returns {Promise<boolean>} Promise resolving to true if HF is supported
    */
   async supportsHF () {
     const infos = await this.info();
@@ -78,8 +79,8 @@ class Service {
   }
 
   /**
-   * Check if a service has username in the hostname or in the path of the api
-   * @return true if the service does not rely on DNS to find a host related to a username
+   * Check if a service has username in the hostname or in the path of the API.
+   * @returns {Promise<boolean>} Promise resolving to true if the service does not rely on DNS to find a host related to a username
    */
   async isDnsLess () {
     const infos = await this.info();
@@ -107,8 +108,8 @@ class Service {
 
   /**
    * Return assets property content
-   * @param {boolean?} forceFetch If true, will force fetching service info.
-   * @returns {Promise<ServiceAssets>} Promise to ServiceAssets
+   * @param {boolean} [forceFetch] If true, will force fetching service info.
+   * @returns {Promise<ServiceAssets|null>} Promise to ServiceAssets
    */
   async assets (forceFetch) {
     if (!forceFetch && this._assets) {
@@ -134,9 +135,9 @@ class Service {
 
   /**
    * Return an API endpoint from a username and token
-   * @param {string} username
-   * @param {string} [token]
-   * @return {APIEndpoint}
+   * @param {string} username - The username
+   * @param {string} [token] - Optional authorization token
+   * @returns {Promise<APIEndpoint>} Promise resolving to the API endpoint URL
    */
   async apiEndpointFor (username, token) {
     const serviceInfo = await this.info();
@@ -144,16 +145,16 @@ class Service {
   }
 
   /**
-   * Return an API endpoint from a username and token and a ServiceInfo.
-   * This is method is rarely used. See **apiEndpointFor** as an alternative.
-   * @param {ServiceInfo} serviceInfo
-   * @param {string} username
-   * @param {string} [token]
-   * @return {APIEndpoint}
+   * Return an API endpoint from a username, token and ServiceInfo.
+   * This method is rarely used. See **apiEndpointFor** as an alternative.
+   * @param {ServiceInfo} serviceInfo - The service info object containing API URL template
+   * @param {string} username - The username
+   * @param {string} [token] - Optional authorization token
+   * @returns {APIEndpoint} The constructed API endpoint URL
    */
   static buildAPIEndpoint (serviceInfo, username, token) {
     const endpoint = serviceInfo.api.replace('{username}', username);
-    return utils.buildAPIEndpoint({ endpoint: endpoint, token: token });
+    return utils.buildAPIEndpoint({ endpoint, token });
   }
 
   /**
@@ -169,32 +170,31 @@ class Service {
   async login (username, password, appId, originHeader) {
     const apiEndpoint = await this.apiEndpointFor(username);
 
-    try {
-      const headers = { accept: 'json' };
-      originHeader = originHeader || (await this.info()).register;
-      if (!utils.isBrowser()) {
-        headers.Origin = originHeader;
+    const headers = {};
+    originHeader = originHeader || (await this.info()).register;
+    if (!utils.isBrowser()) {
+      headers.Origin = originHeader;
+    }
+    const { response, body } = await utils.fetchPost(
+      apiEndpoint + 'auth/login',
+      { username, password, appId },
+      headers
+    );
+
+    if (!response.ok) {
+      if (body?.error?.message) {
+        throw new Error(body.error.message);
       }
-      const res = await utils.superagent.post(apiEndpoint + 'auth/login')
-        .set(headers)
-        .send({ username: username, password: password, appId: appId });
+      throw new Error('Login failed: ' + JSON.stringify(body));
+    }
 
-      if (!res.body.token) {
-        throw new Error('Invalid login response: ' + res.body);
-      }
-      return new Connection(
-        Service.buildAPIEndpoint(await this.info(), username, res.body.token),
-        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);
-      }
-      throw (e);
+    if (!body.token) {
+      throw new Error('Invalid login response: ' + JSON.stringify(body));
     }
+    return new Connection(
+      Service.buildAPIEndpoint(await this.info(), username, body.token),
+      this // Pre load Connection with service
+    );
   }
 }
 
@@ -215,5 +215,7 @@ const Connection = require('./Connection');
  * @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 {Object} [assets] Holder for service specific Assets (icons, css, ...)
- * @property {String} [assets.definitions] URL to json object with assets definitions
+ * @property {string} [assets.definitions] URL to json object with assets definitions
+ * @property {Object} [features] Platform feature flags
+ * @property {boolean} [features.noHF] True if HF data is not supported
  */

package/src/ServiceAssets.js

@@ -16,8 +16,8 @@ const utils = require('./utils.js');
 class ServiceAssets {
   /**
    * Private => use ServiceAssets.setup()
-   * @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`
+   * @param {Object} assets The content of service/info.assets properties.
+   * @param {string} assetsURL Url point to assets of the service of a Pryv platform
    */
   constructor (assets, assetsURL) {
     this._assets = assets;
@@ -25,13 +25,13 @@ class ServiceAssets {
   }
 
   /**
-   * Load Assets definition
-   * @param {string} pryvServiceAssetsSourceUrl
-   * @returns {ServiceAssets}
+   * Load Assets definition from URL
+   * @param {string} pryvServiceAssetsSourceUrl - URL to the assets definition JSON
+   * @returns {Promise<ServiceAssets>} Promise resolving to ServiceAssets instance
    */
   static async setup (pryvServiceAssetsSourceUrl) {
-    const res = await utils.superagent.get(pryvServiceAssetsSourceUrl).set('accept', 'json');
-    return new ServiceAssets(res.body, pryvServiceAssetsSourceUrl);
+    const { body } = await utils.fetchGet(pryvServiceAssetsSourceUrl);
+    return new ServiceAssets(body, pryvServiceAssetsSourceUrl);
   }
 
   /**
@@ -85,6 +85,8 @@ class ServiceAssets {
    * Set service Favicon to Web Page
    */
   setFavicon () {
+    /** @type {HTMLLinkElement} */
+    // @ts-ignore - querySelector returns Element but we know it's HTMLLinkElement
     const link = document.querySelector("link[rel*='icon']") || document.createElement('link');
     link.type = 'image/x-icon';
     link.rel = 'shortcut icon';
@@ -110,18 +112,20 @@ class ServiceAssets {
 
   /**
    * Get HTML for Login Button
+   * @returns {Promise<string>} Promise resolving to HTML string
    */
   async loginButtonGetHTML () {
-    const res = await utils.superagent.get(this.relativeURL(this._assets['lib-js'].buttonSignIn.html)).set('accept', 'html');
-    return res.text;
+    const { text } = await utils.fetchGetText(this.relativeURL(this._assets['lib-js'].buttonSignIn.html));
+    return text;
   }
 
   /**
    * Get Messages strings for Login Button
+   * @returns {Promise<Object.<string, string>>} Promise resolving to messages object
    */
   async loginButtonGetMessages () {
-    const res = await utils.superagent.get(this.relativeURL(this._assets['lib-js'].buttonSignIn.messages)).set('accept', 'json');
-    return res.body;
+    const { body } = await utils.fetchGet(this.relativeURL(this._assets['lib-js'].buttonSignIn.messages));
+    return body;
   }
 }
 
@@ -153,8 +157,10 @@ function loadCSS (url) {
   \*/
 
 function relPathToAbs (baseUrlString, sRelPath) {
+  /** @type {Location|HTMLAnchorElement} */
   var baseLocation = location;
   if (baseUrlString) {
+    // @ts-ignore - HTMLAnchorElement has compatible URL properties
     baseLocation = document.createElement('a');
     baseLocation.href = baseUrlString;
   }