From 722874c67731a0929f1ab1cc86aacc83317290ff Mon Sep 17 00:00:00 2001 From: ailinvenerus Date: Thu, 21 Dec 2023 11:17:28 +0000 Subject: [PATCH] feat: add automatic doc generation and update pipeline --- .github/workflows/update-doc.yml | 37 +++++++++ .gitignore | 1 + package.json | 5 +- src/auth.ts | 129 +++++++++++++++---------------- src/errors.ts | 40 +++++----- 5 files changed, 125 insertions(+), 87 deletions(-) create mode 100644 .github/workflows/update-doc.yml diff --git a/.github/workflows/update-doc.yml b/.github/workflows/update-doc.yml new file mode 100644 index 0000000..13c3581 --- /dev/null +++ b/.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/action-pull-request-another-repo@v1.3.1 + 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: 'ailin@scribelabs.ai' + user_name: 'ailinvenerus' diff --git a/.gitignore b/.gitignore index 1f3d5d1..c9b7051 100644 --- a/.gitignore +++ b/.gitignore @@ -86,6 +86,7 @@ typings/ # Nuxt.js build / generate output .nuxt dist +docs # Gatsby files .cache/ diff --git a/package.json b/package.json index f2a8af1..c06a331 100644 --- a/package.json +++ b/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": "^0.34.1" }, @@ -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" } } diff --git a/src/auth.ts b/src/auth.ts index 023b8cb..b26322b 100644 --- a/src/auth.ts +++ b/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 { - /** - * 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 { - /** - * 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 { - /** - * 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 { - /** - * 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 { diff --git a/src/errors.ts b/src/errors.ts index f860074..0684a6c 100644 --- a/src/errors.ts +++ b/src/errors.ts @@ -1,11 +1,11 @@ +/** +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'; @@ -13,13 +13,13 @@ export class UnauthorizedError 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. +*/ 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';