From: Justin Wind Date: Sat, 10 Jun 2023 18:55:01 +0000 (-0700) Subject: minor doc fixes X-Git-Tag: v1.3.0~2 X-Git-Url: https://git.squeep.com/?a=commitdiff_plain;h=6c3dbdc13dc125d4faa30d5138a8ada7d14e0ed1;p=squeep-indieauth-helper minor doc fixes --- diff --git a/README.md b/README.md index 47c8cc6..b3f85bf 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # IndieAuth Helper -Just some abstractions for interacting with IndieAuth sites, basically wrapping axios and mf2 parsing. +Just some abstractions for interacting with IndieAuth sites, basically wrapping `got` and `microformats-parser` mf2 parsing and some other fiddly bits. This is currently quite opinionated, and likely is only really useful in the context of Squeep Framework Applications. @@ -9,8 +9,8 @@ Notable methods on the Communication class: - `static async generatePKCE(length)` Create a code and verifier for use in an IndieAuth transaction. -- `validateProfile(url)` - Check that a urls meets specification requirements to be a profile. +- `async validateProfile(url)` + Check that a url meets specification requirements to be a profile. - `async fetchProfile(urlObject)` Retrieve profile information from an endpoint. diff --git a/lib/common.js b/lib/common.js index c1b8703..b52b819 100644 --- a/lib/common.js +++ b/lib/common.js @@ -27,6 +27,7 @@ const gotResponseLogData = (res) => { 'statusMessage', 'headers', 'body', + 'error', ]); if (typeof res.body === 'string') { data.body = logTruncate(data.body, 100); diff --git a/lib/communication.js b/lib/communication.js index 18a6e58..d160707 100644 --- a/lib/communication.js +++ b/lib/communication.js @@ -399,6 +399,7 @@ class Communication { * N.B. Sets isLoopback on urlObj * @param {URL} urlObj * @param {Boolean} allowLoopback + * @param {Boolean} resolveHostname * @returns {Promise} */ static async _urlNamedHost(urlObj, allowLoopback, resolveHostname) { @@ -488,9 +489,9 @@ class Communication { * Ensure a url meets the requirements to be a profile uri. * @param {String} url * @param {Object} validationOptions - * @param {Boolean} validationOptions.allowLoopback - * @param {Boolean} validationOptions.resolveHostname - * @returns {Promise} + * @param {Boolean=} validationOptions.allowLoopback default is false, following spec + * @param {Boolean=} validationOptions.resolveHostname default is false, following spec + * @returns {Promise} */ async validateProfile(url, validationOptions) { const _scope = _fileScope('validateProfile'); @@ -526,11 +527,11 @@ class Communication { /** * Ensure a url meets the requirements to be a client identifier. - * Sets 'isLoopback' on returned URL object to true if hostname is or resolves to a loopback ip. + * Sets 'isLoopback' on returned URL object to true if hostname is - or resolves to - a loopback ip. * @param {String} url * @param {Object} validationOptions - * @param {Boolean} validationOptions.allowLoopback - * @param {Boolean} validationOptions.resolveHostname + * @param {Boolean=} validationOptions.allowLoopback default is true, following spec + * @param {Boolean=} validationOptions.resolveHostname default is true, following spec * @returns {Promise} */ async validateClientIdentifier(url, validationOptions) { @@ -574,7 +575,7 @@ class Communication { * Retrieve and parse client identifier endpoint data. * N.B. Assumes urlObj has passed validateClientIdentifier. * @param {URL} urlObj - * @returns {ClientIdentifierData|undefined} mf2 data filtered for h-app items, or undefined if url could not be fetched + * @returns {Promise} mf2 data filtered for h-app items, or undefined if url could not be fetched */ async fetchClientIdentifier(urlObj) { const _scope = _fileScope('fetchClientIdentifier'); @@ -647,8 +648,9 @@ class Communication { /** * Fetch the relevant microformat data from profile url h-card information, * and authorization server metadata. + * N.B. Assumes urlObj has passed validateProfile * @param {URL} urlObj - * @returns {ProfileData} mf2 data filtered for select fields from h-card + * @returns {Promise} mf2 data filtered for select fields from h-card */ async fetchProfile(urlObj) { const _scope = _fileScope('fetchProfile'); @@ -751,7 +753,7 @@ class Communication { * @param {String} codeVerifier * @param {String} clientId * @param {String} redirectURI - * @returns {Object} + * @returns {Promise} */ async redeemCode(urlObj, code, codeVerifier, clientId, redirectURI) { const _scope = _fileScope('redeemCode'); @@ -790,7 +792,7 @@ class Communication { * @param {Strin} codeVerifier * @param {String} clientId * @param {String} redirectURI - * @returns {Object} + * @returns {Promise} */ async redeemProfileCode(urlObj, code, codeVerifier, clientId, redirectURI) { return this.redeemCode(urlObj, code, codeVerifier, clientId, redirectURI); @@ -802,6 +804,7 @@ class Communication { * @param {URL} introspectionUrlObj * @param {String} authorizationHeader * @param {String} token + * @returns {Promise} */ async introspectToken(introspectionUrlObj, authorizationHeader, token) { const _scope = _fileScope('introspectToken'); @@ -863,7 +866,7 @@ class Communication { * @param {URL} resourceUrlObj * @param {URL} subjectUrlObj * @param {String} ticket - * @returns {Promise} + * @returns {Promise} */ async deliverTicket(ticketEndpointUrlObj, resourceUrlObj, subjectUrlObj, ticket) { const _scope = _fileScope('deliverTicket');