Automate doc

.github/workflows/update-doc.yml

@@ -0,0 +1,37 @@
+name: Update docs
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  create-files:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install deps
+        run: npm install
+      - name: Build project
+        run: npm run build:lib && npm run build:bin
+      - name: Create md files
+        run: npx typedoc --excludePrivate --out ./docs --plugin typedoc-plugin-markdown ./src
+      - name: Compile md files
+        run: npx concat-md --decrease-title-levels --ignore README.md --dir-name-as-title docs > docs/reference.md
+      - name: Update docs website
+        uses: car-on-sale/[email protected]
+        env:
+          API_TOKEN_GITHUB: ${{ secrets.WEBSITE_GITHUB_TOKEN }}
+          GH_TOKEN: ${{ secrets.WEBSITE_GITHUB_TOKEN }}
+        with:
+          source_folder: 'docs'
+          destination_repo: 'ScribeLabsAI/documentation'
+          destination_folder: 'docs/SDK/auth-node'
+          destination_base_branch: 'master'
+          destination_head_branch: 'auth-node-update'
+          commit_msg: 'docs(authNode): Update Auth Node doc'
+          pr_title: 'Update Auth Node doc'
+          pull_request_reviewers: 'EHadoux'
+          user_email: '[email protected]'
+          user_name: 'ailinvenerus'

.gitignore

@@ -86,6 +86,7 @@ typings/
 # Nuxt.js build / generate output
 .nuxt
 dist
+docs
 
 # Gatsby files
 .cache/

package.json

@@ -43,6 +43,8 @@
     "otplib": "^12.0.1",
     "prettier": "^3.0.0",
     "prettier-plugin-organize-imports": "^3.0.0",
+    "typedoc": "^0.25.4",
+    "typedoc-plugin-markdown": "^3.17.1",
     "typescript": "^5.0.2",
     "vitest": "^1.0.4"
   },
@@ -53,6 +55,7 @@
     "@smithy/signature-v4": "^2.0.1",
     "amazon-cognito-identity-js": "^6.2.0",
     "aws-sdk": "^2.1379.0",
-    "commander": "^11.0.0"
+    "commander": "^11.0.0",
+    "concat-md": "^0.5.1"
   }
 }

src/auth.ts

@@ -149,15 +149,15 @@ export class Auth {
     return true;
   }
 
+  /**
+   * Allows a user to enter a confirmation code sent to their email to reset a forgotten password.
+   *
+   * @param username - Username (usually an email address).
+   * @param password - Password associated with this username.
+   * @param confirmationCode - Confirmation code sent to the user's email.
+   * @returns A boolean indicating the success of the password reset.
+   */
   async forgotPassword(username: string, password: string, confirmationCode: string) {
-    /**
-     * Allows a user to enter a confirmation code sent to their email to reset a forgotten password.
-     *
-     * @param username - Username (usually an email address).
-     * @param password - Password associated with this username.
-     * @param confirmationCode - Confirmation code sent to the user's email.
-     * @returns A boolean indicating the success of the password reset.
-     */
     if (!this.clientId) throw new MissingIdError('Missing client ID');
     try {
       await this.client.confirmForgotPassword({
@@ -174,20 +174,21 @@ export class Auth {
     }
   }
 
+  /**
+   * A user gets their tokens (refreshToken, accessToken, and idToken).
+   * The password from params never abandons the user's machine.
+   *
+   * @param param - Username and password OR refreshToken.
+   * @param param.username - Username (usually an email address).
+   * @param param.password - Password associated with this username.
+   *                   OR
+   * @param param.refreshToken - Refresh token to use.
+   * @returns Tokens - Object containing the refreshToken, accessToken, and idToken.
+   *                   { "refreshToken": string, "accessToken": string, "idToken": string }
+   * @returns Challenge - Object containing the challengeName, challengeParameters, and user.
+   *                      { "challengeName": string, "challengeParameters": { "FRIENDLY_DEVICE_NAME": string }, "user": CognitoUser }
+   */
   async getTokens(param: UsernamePassword | RefreshToken): Promise<Tokens | Challenge> {
-    /**
-     * A user gets their tokens (refreshToken, accessToken, and idToken).
-     * The password from params never abandons the user's machine.
-     *
-     * @param username - Username (usually an email address).
-     * @param password - Password associated with this username.
-     *                   OR
-     * @param refreshToken - Refresh token to use.
-     * @returns Tokens - Object containing the refreshToken, accessToken, and idToken.
-     *                   { "refreshToken": string, "accessToken": string, "idToken": string }
-     * @returns Challenge - Object containing the challengeName, challengeParameters, and user.
-     *                      { "challengeName": string, "challengeParameters": { "FRIENDLY_DEVICE_NAME": string }, "user": CognitoUser }
-     */
     if ('username' in param && 'password' in param) {
       const { username, password } = param;
       return await this.getTokensWithPair(username, password);
@@ -264,19 +265,19 @@ export class Auth {
     }
   }
 
+  /**
+   * Respond to an MFA auth challenge with a code generated from an auth app (e.g. Authy).
+   * @param user - Cognito user.
+   * @param code - Code generated from the auth app.
+   * @param challengeParameters - ChallengeParameters from Challenge.
+   * @returns Tokens - Object containing the refreshToken, accessToken, and idToken.
+   *                   { "refreshToken": string, "accessToken": string, "idToken": string }
+   */
   async respondToAuthChallengeMfa(
     user: CognitoUser,
     code: string,
     challengeParameters: Challenge['challengeParameters']
   ): Promise<Tokens> {
-    /**
-     * Respond to an MFA auth challenge with a code generated from an auth app (e.g. Authy).
-     * @param user - Cognito user.
-     * @param code - Code generated from the auth app.
-     * @param challengeParameters - ChallengeParameters from Challenge.
-     * @returns Tokens - Object containing the refreshToken, accessToken, and idToken.
-     *                   { "refreshToken": string, "accessToken": string, "idToken": string }
-     */
     try {
       const result = await this.respondToMfaChallenge(user, code, challengeParameters);
       if (result) {
@@ -334,13 +335,13 @@ export class Auth {
     }
   }
 
+  /**
+   * A user gets their federated id.
+   *
+   * @param idToken - Id token to use.
+   * @returns A string containing the federatedId.
+   */
   async getFederatedId(idToken: string): Promise<string> {
-    /**
-     * A user gets their federated id.
-     *
-     * @param idToken - Id token to use.
-     * @returns A string containing the federatedId.
-     */
     if (!this.userPoolId) throw new MissingIdError('Missing user pool ID');
     if (!this.fedClient)
       throw new MissingIdError(
@@ -366,15 +367,15 @@ export class Auth {
     }
   }
 
+  /**
+   * A user gets their federated credentials (AccessKeyId, SecretKey and SessionToken).
+   *
+   * @param id - Federated id.
+   * @param idToken - Id token to use.
+   * @returns Credentials - Object containing the AccessKeyId, SecretKey, SessionToken and Expiration.
+   *                   { "AccessKeyId": string, "SecretKey": string, "SessionToken": string, "Expiration": string }
+   */
   async getFederatedCredentials(id: string, idToken: string): Promise<Credentials> {
-    /**
-     * A user gets their federated credentials (AccessKeyId, SecretKey and SessionToken).
-     *
-     * @param id - Federated id.
-     * @param idToken - Id token to use.
-     * @returns Credentials - Object containing the AccessKeyId, SecretKey, SessionToken and Expiration.
-     *                   { "AccessKeyId": string, "SecretKey": string, "SessionToken": string, "Expiration": string }
-     */
     if (!this.userPoolId) throw new MissingIdError('Missing user pool ID');
     if (!this.fedClient)
       throw new MissingIdError(
@@ -403,30 +404,26 @@ export class Auth {
     }
   }
 
+  /**
+   * A user gets a signature for a request.
+   *
+   * @param request - Request to send.
+   * @param credentials - Credentials for the signature creation.
+   * @returns HeaderBag - Headers containing the signature for the request.
+   */
   async getSignatureForRequest(request: HttpRequest, credentials: Credentials) {
-    /**
-     * A user gets a signature for a request.
-     *
-     * @param request - Request to send.
-     * @param credentials - Credentials for the signature creation.
-     * @returns HeaderBag - Headers containing the signature for the request.
-     */
-    try {
-      const signer = new SignatureV4({
-        credentials: {
-          accessKeyId: credentials.AccessKeyId,
-          secretAccessKey: credentials.SecretKey,
-          sessionToken: credentials.SessionToken,
-        },
-        service: 'execute-api',
-        region: 'eu-west-2',
-        sha256: Sha256,
-      });
-      const signatureRequest = await signer.sign(request);
-      return signatureRequest.headers;
-    } catch (err) {
-      throw err;
-    }
+    const signer = new SignatureV4({
+      credentials: {
+        accessKeyId: credentials.AccessKeyId,
+        secretAccessKey: credentials.SecretKey,
+        sessionToken: credentials.SessionToken,
+      },
+      service: 'execute-api',
+      region: 'eu-west-2',
+      sha256: Sha256,
+    });
+    const signatureRequest = await signer.sign(request);
+    return signatureRequest.headers;
   }
 
   // async revokeRefreshToken(refreshToken: string): Promise<boolean> {

src/errors.ts

@@ -1,25 +1,25 @@
+/**
+Exception raised when a user cannot perform an action.
+Possible reasons:
+Username and/or Password are incorrect.
+Refresh token is incorrect.
+MFA code is incorrect or expired.
+*/
 export class UnauthorizedError extends Error {
-  /**
-  Exception raised when a user cannot perform an action.
-  Possible reasons:
-  Username and/or Password are incorrect.
-  Refresh token is incorrect.
-  MFA code is incorrect or expired.
-  */
   constructor(message: string, cause?: Error) {
     super(message);
     this.name = 'UnauthorizedError';
     this.cause = cause;
   }
 }
 
+/**
+Exception raised when an action is performed by a user too many times in a short period.
+Actions that could raise this exception:
+Changing a password.
+Revoking a refresh token.
+*/
 export class TooManyRequestsError extends Error {
-  /**
-  Exception raised when an action is performed by a user too many times in a short period.
-  Actions that could raise this exception:
-  Changing a password.
-  Revoking a refresh token.
-  */
   constructor(message: string, cause?: Error) {
     super(message);
     this.name = 'TooManyRequestsError';
@@ -48,14 +48,14 @@ export class MissingFieldError extends Error {
   }
 }
 
+/**
+ * Exception raised when MFA fails.
+ * Actions that could raise this exception:
+ * A code has expired.
+ * The provided code doesn't match what the server was expecting.
+ *
+ */
 export class MFAError extends Error {
-  /**
-   * Exception raised when MFA fails.
-   * Actions that could raise this exception:
-   * A code has expired.
-   * The provided code doesn't match what the server was expecting.
-   *
-   */
   constructor(message: string) {
     super(message);
     this.name = 'MFAError';