yunohost-admin/app/src/api/api.js

/**
 * API module.
 * @module api
 */

import store from '@/store'
import { openWebSocket, getResponseData, handleError } from './handlers'


/**
 * Options available for an API call.
 *
 * @typedef {Object} Options
 * @property {Boolean} wait - If `true`, will display the waiting modal.
 * @property {Boolean} websocket - if `true`, will open a websocket connection.
 * @property {Boolean} initial - if `true` and an error occurs, the dismiss button will trigger a go back in history.
 * @property {Boolean} asFormData - if `true`, will send the data with a body encoded as `"multipart/form-data"` instead of `"x-www-form-urlencoded"`).
 */


/**
 * Representation of an API call for `api.fetchAll`
 *
 * @typedef {Array} Query
 * @property {String} 0 - "method"
 * @property {String|Object} 1 - "uri", uri to call as string or as an object for cached uris.
 * @property {Object|null} 2 - "data"
 * @property {Options} 3 - "options"
*/


/**
 * Converts an object literal into an `URLSearchParams` that can be turned into a
 * query string or used as a body in a `fetch` call.
 *
 * @param {Object} obj - An object literal to convert.
 * @param {Object} options
 * @param {Boolean} [options.addLocale=false] - Option to append the locale to the query string.
 * @return {URLSearchParams}
 */
export function objectToParams (obj, { addLocale = false } = {}, formData = false) {
  const urlParams = (formData) ? new FormData() : new URLSearchParams()
  for (const [key, value] of Object.entries(obj)) {
    if (Array.isArray(value)) {
      value.forEach(v => urlParams.append(key, v))
    } else {
      urlParams.append(key, value)
    }
  }
  if (addLocale) {
    urlParams.append('locale', store.getters.locale)
  }
  return urlParams
}


export default {
  options: {
    credentials: 'include',
    mode: 'cors',
    headers: {
      // FIXME is it important to keep this previous `Accept` header ?
      // 'Accept': 'application/json, text/javascript, */*; q=0.01',
      // Auto header is :
      // "Accept": "*/*",

      'X-Requested-With': 'XMLHttpRequest'
    }
  },


  /**
   * Generic method to fetch the api without automatic response handling.
   *
   * @param {String} method - a method between 'GET', 'POST', 'PUT' and 'DELETE'.
   * @param {String} uri
   * @param {Object} [data={}] - data to send as body.
   * @param {Options} [options={ wait = true, websocket = true, initial = false, asFormData = false }]
   * @return {Promise<Object|Error>} Promise that resolve the api response data or an error.
   */
  async fetch (
    method,
    uri,
    data = {},
    humanKey = null,
    { wait = true, websocket = true, initial = false, asFormData = false } = {}
  ) {
    // `await` because Vuex actions returns promises by default.
    const request = await store.dispatch('INIT_REQUEST', { method, uri, humanKey, initial, wait, websocket })

    if (websocket) {
      await openWebSocket(request)
    }

    let options = this.options
    if (method === 'GET') {
      uri += `${uri.includes('?') ? '&' : '?'}locale=${store.getters.locale}`
    } else {
      options = { ...options, method, body: objectToParams(data, { addLocale: true }, true) }
    }

    const response = await fetch('/yunohost/api/' + uri, options)
    const responseData = await getResponseData(response)
    store.dispatch('END_REQUEST', { request, success: response.ok, wait })

    return response.ok ? responseData : handleError(request, response, responseData)
  },


  /**
   * Api multiple queries helper.
   * Those calls will act as one (declare optional waiting for one but still create history entries for each)
   * Calls are synchronous since the API can't handle multiple calls.
   *
   * @param {Array<Query>} queries - An array of queries with special representation.
   * @param {Object} [options={}]
   * @param {Boolean}
   * @return {Promise<Array|Error>} Promise that resolve the api responses data or an error.
   */
  async fetchAll (queries, { wait, initial } = {}) {
    const results = []
    if (wait) store.commit('SET_WAITING', true)
    try {
      for (const [method, uri, data, humanKey, options = {}] of queries) {
        if (wait) options.wait = false
        if (initial) options.initial = true
        results.push(await this[method.toLowerCase()](uri, data, humanKey, options))
      }
    } finally {
      // Stop waiting even if there is an error.
      if (wait) store.commit('SET_WAITING', false)
    }

    return results
  },


  /**
   * Api get helper function.
   *
   * @param {String|Object} uri
   * @param {null} [data=null] - for convenience in muliple calls, just pass null.
   * @param {Options} [options={}] - options to apply to the call (default is `{ websocket: false, wait: false }`)
   * @return {Promise<Object|Error>} Promise that resolve the api response data or an error.
   */
  get (uri, data = null, humanKey = null, options = {}) {
    options = { websocket: false, wait: false, ...options }
    if (typeof uri === 'string') return this.fetch('GET', uri, null, humanKey, options)
    return store.dispatch('GET', { ...uri, humanKey, options })
  },


  /**
   * Api post helper function.
   *
   * @param {String|Object} uri
   * @param {String} [data={}] - data to send as body.
   * @param {Options} [options={}] - options to apply to the call
   * @return {Promise<Object|Error>} Promise that resolve the api response data or an error.
   */
  post (uri, data = {}, humanKey = null, options = {}) {
    if (typeof uri === 'string') return this.fetch('POST', uri, data, humanKey, options)
    return store.dispatch('POST', { ...uri, data, humanKey, options })
  },


  /**
   * Api put helper function.
   *
   * @param {String|Object} uri
   * @param {String} [data={}] - data to send as body.
   * @param {Options} [options={}] - options to apply to the call
   * @return {Promise<Object|Error>} Promise that resolve the api response data or an error.
   */
  put (uri, data = {}, humanKey = null, options = {}) {
    if (typeof uri === 'string') return this.fetch('PUT', uri, data, humanKey, options)
    return store.dispatch('PUT', { ...uri, data, humanKey, options })
  },


  /**
   * Api delete helper function.
   *
   * @param {String|Object} uri
   * @param {String} [data={}] - data to send as body.
   * @param {Options} [options={}] - options to apply to the call (default is `{ websocket: false, wait: false }`)
   * @return {Promise<Object|Error>} Promise that resolve the api response data or an error.
   */
  delete (uri, data = {}, humanKey = null, options = {}) {
    if (typeof uri === 'string') return this.fetch('DELETE', uri, data, humanKey, options)
    return store.dispatch('DELETE', { ...uri, data, humanKey, options })
  },

  /**
   * Api reconnection helper. Resolve when server is reachable or fail after n attemps
   *
   * @param {Number} attemps - number of attemps before rejecting
   * @param {Number} delay - delay between calls to the API in ms.
   * @param {Number} initialDelay - delay before calling the API for the first time in ms.
   * @return {Promise<undefined|Error>}
   */
  tryToReconnect ({ attemps = 5, delay = 2000, initialDelay = 0 } = {}) {
    return new Promise((resolve, reject) => {
      const api = this

      function reconnect (n) {
        api.get('logout', {}, { key: 'reconnecting' }).then(resolve).catch(err => {
          if (err.name === 'APIUnauthorizedError') {
            resolve()
          } else if (n < 1) {
            reject(err)
          } else {
            setTimeout(() => reconnect(n - 1), delay)
          }
        })
      }

      if (initialDelay > 0) setTimeout(() => reconnect(attemps), initialDelay)
      else reconnect(attemps)
    })
  }
}