minor doc fixes

diff --git a/README.md b/README.md
index 47c8cc6fc5ba8637f9e8cd610478f70233348c71..b3f85bf3bc1063f9d397694852c5459ccdd9c7ac 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # IndieAuth Helper
 
 # 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.
 
 
 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.
 
 - `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.
 
 - `async fetchProfile(urlObject)`  
   Retrieve profile information from an endpoint.

diff --git a/lib/common.js b/lib/common.js
index c1b8703d58d435a127a80fcfaec70b73358a2a2c..b52b819da963d5172a06779e279cf3e2531acbcb 100644 (file)
--- a/lib/common.js
+++ b/lib/common.js
@@ -27,6 +27,7 @@ const gotResponseLogData = (res) => {
     'statusMessage',
     'headers',
     'body',
     'statusMessage',
     'headers',
     'body',

+    'error',

   ]);
   if (typeof res.body === 'string') {
     data.body = logTruncate(data.body, 100);
   ]);
   if (typeof res.body === 'string') {
     data.body = logTruncate(data.body, 100);

diff --git a/lib/communication.js b/lib/communication.js
index 18a6e588070e39bb49790433885189703a3bc5d0..d160707ee3bb157559bf594da2f16d12cfcf0db3 100644 (file)
--- 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
    * N.B. Sets isLoopback on urlObj
    * @param {URL} urlObj
    * @param {Boolean} allowLoopback

+   * @param {Boolean} resolveHostname

    * @returns {Promise<void>}
    */
   static async _urlNamedHost(urlObj, allowLoopback, resolveHostname) {
    * @returns {Promise<void>}
    */
   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
    * 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<void>}
+   * @param {Boolean=} validationOptions.allowLoopback default is false, following spec
+   * @param {Boolean=} validationOptions.resolveHostname default is false, following spec
+   * @returns {Promise<URL>}

    */
   async validateProfile(url, validationOptions) {
     const _scope = _fileScope('validateProfile');
    */
   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.
 
   /**
    * 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 {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<URL>}
    */
   async validateClientIdentifier(url, validationOptions) {
    * @returns {Promise<URL>}
    */
   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
    * 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<ClientIdentifierData|undefined>} mf2 data filtered for h-app items, or undefined if url could not be fetched

    */
   async fetchClientIdentifier(urlObj) {
     const _scope = _fileScope('fetchClientIdentifier');
    */
   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.
   /**
    * 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
    * @param {URL} urlObj

-   * @returns {ProfileData} mf2 data filtered for select fields from h-card
+   * @returns {Promise<ProfileData>} mf2 data filtered for select fields from h-card

    */
   async fetchProfile(urlObj) {
     const _scope = _fileScope('fetchProfile');
    */
   async fetchProfile(urlObj) {
     const _scope = _fileScope('fetchProfile');


@@ -751,7 +753,7 @@ class Communication {
    * @param {String} codeVerifier
    * @param {String} clientId
    * @param {String} redirectURI
    * @param {String} codeVerifier
    * @param {String} clientId
    * @param {String} redirectURI

-   * @returns {Object}
+   * @returns {Promise<Object>}

    */
   async redeemCode(urlObj, code, codeVerifier, clientId, redirectURI) {
     const _scope = _fileScope('redeemCode');
    */
   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
    * @param {Strin} codeVerifier
    * @param {String} clientId
    * @param {String} redirectURI

-   * @returns {Object}
+   * @returns {Promise<Object>}

    */
   async redeemProfileCode(urlObj, code, codeVerifier, clientId, redirectURI) {
     return this.redeemCode(urlObj, code, codeVerifier, clientId, redirectURI);
    */
   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
    * @param {URL} introspectionUrlObj
    * @param {String} authorizationHeader
    * @param {String} token

+   * @returns {Promise<Object>}

    */
   async introspectToken(introspectionUrlObj, authorizationHeader, token) {
     const _scope = _fileScope('introspectToken');
    */
   async introspectToken(introspectionUrlObj, authorizationHeader, token) {
     const _scope = _fileScope('introspectToken');


@@ -863,7 +866,7 @@ class Communication {
    * @param {URL} resourceUrlObj
    * @param {URL} subjectUrlObj
    * @param {String} ticket
    * @param {URL} resourceUrlObj
    * @param {URL} subjectUrlObj
    * @param {String} ticket

-   * @returns {Promise<AxiosResponse>}
+   * @returns {Promise<Response>}

    */
   async deliverTicket(ticketEndpointUrlObj, resourceUrlObj, subjectUrlObj, ticket) {
     const _scope = _fileScope('deliverTicket');
    */
   async deliverTicket(ticketEndpointUrlObj, resourceUrlObj, subjectUrlObj, ticket) {
     const _scope = _fileScope('deliverTicket');