fix: fix and add missing JSDOC types

src/fetcher/activitypub.js

@@ -33,10 +33,13 @@ module.exports.timeout = 5000
  * @async
  * @param {object} data                           - Data used in the request
  * @param {string} data.url                       - The URL of the account to verify
+ * @param {number} [data.fetcherTimeout]          - Optional timeout for the fetcher
  * @param {object} opts                           - Options used to enable the request
+ * @param {object} opts.claims
+ * @param {object} opts.claims.activitypub
  * @param {string} opts.claims.activitypub.url    - The URL of the verifier account
  * @param {string} opts.claims.activitypub.privateKey   - The private key to sign the request
- * @returns {object}
+ * @returns {Promise<object>}
  */
 module.exports.fn = async (data, opts) => {
   let crypto

src/fetcher/dns.js

@@ -34,7 +34,8 @@ if (jsEnv.isNode) {
    * @async
    * @param {object} data         - Data used in the request
    * @param {string} data.domain  - The targeted domain
-   * @returns {object}
+   * @param {number} [data.fetcherTimeout]  - Optional timeout for the fetcher
+   * @returns {Promise<object>}
    */
   module.exports.fn = async (data, opts) => {
     let timeoutHandle

src/fetcher/graphql.js

@@ -32,7 +32,8 @@ module.exports.timeout = 5000
  * @param {object} data         - Data used in the request
  * @param {string} data.url     - The URL pointing at the GraphQL HTTP endpoint
  * @param {string} data.query   - The GraphQL query to fetch the data containing the proof
- * @returns {object|string}
+ * @param {number} [data.fetcherTimeout]  - Optional timeout for the fetcher
+ * @returns {Promise<object|string>}
  */
 module.exports.fn = async (data, opts) => {
   let timeoutHandle

src/fetcher/http.js

@@ -33,7 +33,8 @@ module.exports.timeout = 5000
  * @param {object} data         - Data used in the request
  * @param {string} data.url     - The URL pointing at targeted content
  * @param {string} data.format  - The format of the targeted content
- * @returns {object|string}
+ * @param {number} [data.fetcherTimeout]  - Optional timeout for the fetcher
+ * @returns {Promise<object|string>}
  */
 module.exports.fn = async (data, opts) => {
   let timeoutHandle

src/fetcher/irc.js

@@ -36,9 +36,12 @@ if (jsEnv.isNode) {
    * @param {object} data                 - Data used in the request
    * @param {string} data.nick            - The nick of the targeted account
    * @param {string} data.domain          - The domain on which the targeted account is registered
+   * @param {number} [data.fetcherTimeout] - Optional timeout for the fetcher
    * @param {object} opts                 - Options used to enable the request
+   * @param {object} opts.claims
+   * @param {object} opts.claims.irc
    * @param {string} opts.claims.irc.nick - The nick to be used by the library to log in
-   * @returns {object}
+   * @returns {Promise<object>}
    */
   module.exports.fn = async (data, opts) => {
     let timeoutHandle

src/fetcher/matrix.js

@@ -33,10 +33,13 @@ module.exports.timeout = 5000
  * @param {object} data                           - Data used in the request
  * @param {string} data.eventId                   - The identifier of the targeted post
  * @param {string} data.roomId                    - The identifier of the room containing the targeted post
+ * @param {number} [data.fetcherTimeout]          - Optional timeout for the fetcher
  * @param {object} opts                           - Options used to enable the request
+ * @param {object} opts.claims
+ * @param {object} opts.claims.matrix
  * @param {string} opts.claims.matrix.instance    - The server hostname on which the library can log in
  * @param {string} opts.claims.matrix.accessToken - The access token required to identify the library ({@link https://www.matrix.org/docs/guides/client-server-api|Matrix docs})
- * @returns {object}
+ * @returns {Promise<object>}
  */
 module.exports.fn = async (data, opts) => {
   let timeoutHandle

src/fetcher/telegram.js

@@ -34,9 +34,12 @@ module.exports.timeout = 5000
  * @param {object} data                          - Data used in the request
  * @param {string} data.chat                     - Telegram public chat username
  * @param {string} data.user                     - Telegram user username
+ * @param {number} [data.fetcherTimeout]         - Optional timeout for the fetcher
  * @param {object} opts                          - Options used to enable the request
+ * @param {object} opts.claims
+ * @param {object} opts.claims.telegram
  * @param {string} opts.claims.telegram.token    - The Telegram Bot API token
- * @returns {object|string}
+ * @returns {Promise<object|string>}
  */
 module.exports.fn = async (data, opts) => {
   let timeoutHandle
@@ -47,7 +50,7 @@ module.exports.fn = async (data, opts) => {
     )
   })
 
-  const apiPromise = (method) => new Promise((resolve, reject) => {
+  const apiPromise = (/** @type {string} */ method) => new Promise((resolve, reject) => {
     try {
       validator.isAscii(opts.claims.telegram.token)
     } catch (err) {

src/fetcher/xmpp.js

@@ -60,11 +60,14 @@ if (jsEnv.isNode) {
    * @async
    * @param {object} data                       - Data used in the request
    * @param {string} data.id                    - The identifier of the targeted account
+   * @param {number} [data.fetcherTimeout]      - Optional timeout for the fetcher
    * @param {object} opts                       - Options used to enable the request
+   * @param {object} opts.claims
+   * @param {object} opts.claims.xmpp
    * @param {string} opts.claims.xmpp.service   - The server hostname on which the library can log in
    * @param {string} opts.claims.xmpp.username  - The username used to log in
    * @param {string} opts.claims.xmpp.password  - The password used to log in
-   * @returns {object}
+   * @returns {Promise<object>}
    */
   module.exports.fn = async (data, opts) => {
     try {

src/keys.js

@@ -30,7 +30,7 @@ const Claim = require('./claim')
  * @function
  * @param {string} identifier                         - Fingerprint or email address
  * @param {string} [keyserverDomain=keys.openpgp.org] - Domain of the keyserver
- * @returns {openpgp.PublicKey}
+ * @returns {Promise<openpgp.PublicKey>}
  * @example
  * const key1 = doip.keys.fetchHKP('alice@domain.tld');
  * const key2 = doip.keys.fetchHKP('123abc123abc');
@@ -67,7 +67,7 @@ const fetchHKP = async (identifier, keyserverDomain) => {
  * Fetch a public key using Web Key Directory
  * @function
  * @param {string} identifier - Identifier of format 'username@domain.tld`
- * @returns {openpgp.PublicKey}
+ * @returns {Promise<openpgp.PublicKey>}
  * @example
  * const key = doip.keys.fetchWKD('alice@domain.tld');
  */
@@ -79,7 +79,7 @@ const fetchWKD = async (identifier) => {
 
   const publicKey = await wkd
     .lookup(lookupOpts)
-    .catch((error) => {
+    .catch((/** @type {Error} */ error) => {
       throw new Error(`Key does not exist or could not be fetched (${error})`)
     })
 
@@ -100,7 +100,7 @@ const fetchWKD = async (identifier) => {
  * @function
  * @param {string} username     - Keybase username
  * @param {string} fingerprint  - Fingerprint of key
- * @returns {openpgp.PublicKey}
+ * @returns {Promise<openpgp.PublicKey>}
  * @example
  * const key = doip.keys.fetchKeybase('alice', '123abc123abc');
  */
@@ -114,12 +114,12 @@ const fetchKeybase = async (username, fingerprint) => {
         responseType: 'text'
       }
     )
-      .then((response) => {
+      .then((/** @type {import('axios').AxiosResponse} */ response) => {
         if (response.status === 200) {
           return response
         }
       })
-      .then((response) => response.data)
+      .then((/** @type {import('axios').AxiosResponse} */ response) => response.data)
   } catch (e) {
     throw new Error(`Error fetching Keybase key: ${e.message}`)
   }
@@ -136,7 +136,7 @@ const fetchKeybase = async (username, fingerprint) => {
  * Get a public key from plaintext data
  * @function
  * @param {string} rawKeyContent - Plaintext ASCII-formatted public key data
- * @returns {openpgp.PublicKey}
+ * @returns {Promise<openpgp.PublicKey>}
  * @example
  * const plainkey = `-----BEGIN PGP PUBLIC KEY BLOCK-----
  *
@@ -161,7 +161,7 @@ const fetchPlaintext = async (rawKeyContent) => {
  * Fetch a public key using an URI
  * @function
  * @param {string} uri - URI that defines the location of the key
- * @returns {openpgp.PublicKey}
+ * @returns {Promise<openpgp.PublicKey>}
  * @example
  * const key1 = doip.keys.fetchURI('hkp:alice@domain.tld');
  * const key2 = doip.keys.fetchURI('hkp:123abc123abc');
@@ -207,7 +207,7 @@ const fetchURI = async (uri) => {
  * This function will also try and parse the input as a plaintext key
  * @function
  * @param {string} identifier - URI that defines the location of the key
- * @returns {openpgp.PublicKey}
+ * @returns {Promise<openpgp.PublicKey>}
  * @example
  * const key1 = doip.keys.fetch('alice@domain.tld');
  * const key2 = doip.keys.fetch('123abc123abc');
@@ -251,7 +251,7 @@ const fetch = async (identifier) => {
  * Process a public key to get user data and claims
  * @function
  * @param {openpgp.PublicKey} publicKey - The public key to process
- * @returns {object}
+ * @returns {Promise<object>}
  * @example
  * const key = doip.keys.fetchURI('hkp:alice@domain.tld');
  * const data = doip.keys.process(key);

src/signatures.js

@@ -28,6 +28,7 @@ const keys = require('./keys')
  * @returns {Promise<object>}
  */
 const process = async (signature) => {
+  /** @type {openpgp.CleartextMessage} */
   let sigData
   const result = {
     fingerprint: null,
@@ -131,7 +132,7 @@ const process = async (signature) => {
   let userData
 
   if (signersUserID) {
-    result.key.data.users.forEach((user) => {
+    result.key.data.users.forEach((/** @type {{ userID: { email: string; }; }} */ user) => {
       if (user.userID.email === signersUserID) {
         userData = user
       }

src/utils.js

@@ -25,6 +25,7 @@ const E = require('./enums')
  * @param {string} type                 - The name of the fetcher the proxy must use
  * @param {object} data                 - The data the proxy must provide to the fetcher
  * @param {object} opts                 - Options to enable the request
+ * @param {object} opts.proxy           - Proxy related options
  * @param {object} opts.proxy.hostname  - The hostname of the proxy server
  * @returns {string}
  */
@@ -49,7 +50,7 @@ const generateProxyURL = (type, data, opts) => {
 /**
  * Generate the string that must be found in the proof to verify a claim
  * @param {string} fingerprint  - The fingerprint of the claim
- * @param {number} format       - The claim's format (see {@link module:enums~ClaimFormat|enums.ClaimFormat})
+ * @param {string} format       - The claim's format (see {@link module:enums~ClaimFormat|enums.ClaimFormat})
  * @returns {string}
  */
 const generateClaim = (fingerprint, format) => {
@@ -66,7 +67,7 @@ const generateClaim = (fingerprint, format) => {
 /**
  * Get the URIs from a string and return them as an array
  * @param {string} text         - The text that may contain URIs
- * @returns {Array.string}
+ * @returns {Array<string>}
  */
 const getUriFromString = (text) => {
   const re = /((([A-Za-z0-9]+:(?:\/\/)?)(?:[-;:&=+$,\w]+@)?[A-Za-z0-9.-]+|(?:www\.|[-;:&=+$,\w]+@)[A-Za-z0-9.-]+)((?:\/[+~%/.\w\-_]*)?\??(?:[-+=&;%@.\w_]*)#?(?:[.!/\\\w]*))?)/gi

src/verifications.js

@@ -23,6 +23,16 @@ const entities = require('entities')
  * @ignore
  */
 
+/**
+ * @function
+ * @param {string} data
+ * @param {object} params
+ * @param {string} params.target
+ * @param {string} params.claimFormat
+ * @param {string} params.proofEncodingFormat
+ * @param {string} [params.claimRelation]
+ * @returns {Promise<boolean>}
+ */
 const containsProof = async (data, params) => {
   const fingerprintFormatted = utils.generateClaim(params.target, params.claimFormat)
   const fingerprintURI = utils.generateClaim(params.target, E.ClaimFormat.URI)
@@ -122,6 +132,7 @@ const containsProof = async (data, params) => {
       if (result) continue
 
       const candidate = uris[index]
+      /** @type {URL} */
       let candidateURL
 
       try {
@@ -135,7 +146,8 @@ const containsProof = async (data, params) => {
       }
 
       // Using fetch -> axios doesn't find the ariadne-identity-proof header
-      const response = await fetch(candidate, { // eslint-disable-line
+      /** @type {Response} */
+      const response = await fetch(candidate, {
         method: 'HEAD'
       })
         .catch(e => {
@@ -155,6 +167,17 @@ const containsProof = async (data, params) => {
   return result
 }
 
+/**
+ * @function
+ * @param {any} proofData
+ * @param {string} checkPath
+ * @param {object} params
+ * @param {string} params.target
+ * @param {string} params.claimFormat
+ * @param {string} params.proofEncodingFormat
+ * @param {string} [params.claimRelation]
+ * @returns {Promise<boolean>}
+ */
 const runJSON = async (proofData, checkPath, params) => {
   if (!proofData) {
     return false
@@ -205,7 +228,7 @@ const runJSON = async (proofData, checkPath, params) => {
  * @param {object} proofData    - The proof data
  * @param {object} claimData    - The claim data
  * @param {string} fingerprint  - The fingerprint
- * @returns {object}
+ * @returns {Promise<object>}
  */
 const run = async (proofData, claimData, fingerprint) => {
   const res = {