chore: added documentation to most important methods (#16)

Author: birme

jsdoc.json

@@ -5,10 +5,22 @@
   "plugins": ["node_modules/better-docs/typescript"],
   "source": {
     "include": ["readme.md", "src"],
-    "includePattern": "\\.(jsx|js|ts|tsx)$",
-    "excludePattern": "(node_modules/|docs)"
+    "includePattern": "\\.(ts)$",
+    "excludePattern": "(node_modules/|docs|lib/)"
   },
   "opts": {
-    "destination": "./docs/"
+    "destination": "./docs/",
+    "recurse": true
+  },
+  "templates": {
+    "default": {
+      "outputSourceFiles": false
+    },
+    "cleverLinks": false,
+    "monospaceLinks": false,
+    "search": true,
+    "better-docs": {
+      "hideGenerator": true
+    }
   }
 }

src/cat.ts

@@ -84,6 +84,9 @@ const claimTypeValidators: { [key: string]: (value: string) => boolean } = {
 
 const CWT_TAG = 61;
 
+/**
+ * Common Access Token Claims
+ */
 export type CommonAccessTokenClaims = {
   [key: string]: string | number | Map<number, any>;
 };
@@ -96,14 +99,34 @@ export type CommonAccessTokenValue =
   | Buffer
   | Map<number, any>;
 
+/**
+ * CWT Encryption Key
+ */
 export interface CWTEncryptionKey {
+  /**
+   * Key
+   */
   k: Buffer;
+  /**
+   * Key ID
+   */
   kid: string;
 }
+
+/**
+ * CWT Decryption Key
+ */
 export interface CWTDecryptionKey {
+  /**
+   * Key
+   */
   k: Buffer;
+  /**
+   * Key ID
+   */
   kid: string;
 }
+
 export interface CWTSigningKey {
   d: Buffer;
   kid: string;
@@ -157,6 +180,9 @@ function updateMapFromDict(
   return claims;
 }
 
+/**
+ * Common Access Token
+ */
 export class CommonAccessToken {
   private payload: Map<number, CommonAccessTokenValue>;
   private data?: Buffer;
@@ -166,9 +192,21 @@ export class CommonAccessToken {
     this.payload = updateMapFromClaims(claims);
   }
 
+  /**
+   * Create a CWT CAT token
+   */
   public async mac(
+    /**
+     * Encryption key
+     */
     key: CWTEncryptionKey,
+    /**
+     * Algorithm to use
+     */
     alg: string,
+    /**
+     * Options
+     */
     opts?: {
       addCwtTag: boolean;
     }
@@ -198,6 +236,9 @@ export class CommonAccessToken {
     this.kid = key.kid;
   }
 
+  /**
+   * Parse a CWT CAT token
+   */
   public async parse(
     token: Buffer,
     key: CWTDecryptionKey,
@@ -253,6 +294,9 @@ export class CommonAccessToken {
     }
   }
 
+  /**
+   * Validate all claims in the token
+   */
   public async isValid(opts: CatValidationOptions): Promise<boolean> {
     this.validateTypes();
 
@@ -372,6 +416,9 @@ export class CommonAccessToken {
   }
 }
 
+/**
+ * Common Access Token Factory
+ */
 export class CommonAccessTokenFactory {
   public static async fromSignedToken(
     base64encoded: string,

src/errors.ts

@@ -1,53 +1,80 @@
 import { CommonAccessTokenValue } from './cat';
 
+/**
+ * Error thrown when a key is not found for validating a token
+ */
 export class KeyNotFoundError extends Error {
   constructor() {
     super(`Failed to validate token signature with any of the available keys`);
   }
 }
 
+/**
+ * Error thrown when an invalid claim type is found
+ */
 export class InvalidClaimTypeError extends Error {
   constructor(claim: string, value: CommonAccessTokenValue) {
     super(`Invalid claim type for ${claim}: ${typeof value}`);
   }
 }
 
+/**
+ * Error thrown when an invalid issuer is found
+ */
 export class InvalidIssuerError extends Error {
   constructor(issuer: CommonAccessTokenValue | undefined) {
     super(`Invalid issuer: ${issuer || 'undefined'}`);
   }
 }
 
+/**
+ * Error thrown when token has expired
+ */
 export class TokenExpiredError extends Error {
   constructor() {
     super('Token has expired');
   }
 }
 
+/**
+ * Error thrown when audience is not valid
+ */
 export class InvalidAudienceError extends Error {
   constructor(audience: string[]) {
     super(`Invalid audience: ${audience.join(', ')}`);
   }
 }
 
+/**
+ * Error thrown when token is not yet active
+ */
 export class TokenNotActiveError extends Error {
   constructor() {
     super('Token is not yet active');
   }
 }
 
+/**
+ * Error thrown when CATU claim is invalid
+ */
 export class InvalidCatuError extends Error {
   constructor(reason: string) {
     super(reason);
   }
 }
 
+/**
+ * Error thrown when trying to access a URI that does not match the allowed URIs
+ */
 export class UriNotAllowedError extends Error {
   constructor(reason: string) {
     super(reason);
   }
 }
 
+/**
+ * Error thrown when trying to renew a claim that is not renewable
+ */
 export class RenewalClaimError extends Error {
   constructor(reason: string) {
     super(reason);