[add] simple OAuth 2 controller

[optimize] update Read Me documents

ReadMe.md

@@ -9,7 +9,7 @@
 [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)][6]
 [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)][7]
 
-## Feature
+## Technology stack
 
 1. HTTP server: [Koa][8]
 2. Controller framework: [Routing Controllers][9]
@@ -18,22 +18,30 @@
 5. API document: [Swagger][13]
 6. Mock API: [OpenAPI backend][14]
 
+## Major features
+
+1. [API entry & Health checking](source/controller/Base.ts)
+2. [User & Session](source/controller/User.ts)
+3. [OAuth sign in](source/controller/OAuth.ts)
+    - recommend to use with [Next SSR middleware][15]
+4. [Activity logging](source/controller/ActivityLog.ts)
+
 ## Best practice
 
 1.  Install GitHub apps in your organization or account:
 
-    1.  [Probot settings][15]: set up Issue labels & Pull Request rules
-    2.  [PR badge][16]: set up Online [VS Code][17] editor entries in Pull Request description
+    1.  [Probot settings][16]: set up Issue labels & Pull Request rules
+    2.  [PR badge][17]: set up Online [VS Code][18] editor entries in Pull Request description
 
-2.  Click the **[<kbd>Use this template</kbd>][18] button** on the top of this GitHub repository's home page, then create your own repository in the app-installed namespace above
+2.  Click the **[<kbd>Use this template</kbd>][19] button** on the top of this GitHub repository's home page, then create your own repository in the app-installed namespace above
 
 3.  Click the **[<kbd>Open in GitHub codespaces</kbd>][8] button** on the top of ReadMe file, then an **online VS Code development environment** will be started immediately
 
-4.  Recommend to add a [Notification step in GitHub actions][19] for your Team IM app
+4.  Recommend to add a [Notification step in GitHub actions][20] for your Team IM app
 
-5.  Remind the PMs & users of your product to submit **Feature/Enhancement** requests or **Bug** reports with [Issue forms][20] instead of IM messages or Mobile Phone calls
+5.  Remind the PMs & users of your product to submit **Feature/Enhancement** requests or **Bug** reports with [Issue forms][21] instead of IM messages or Mobile Phone calls
 
-6.  Collect all these issues into [Project kanbans][21], then create **Pull requests** & add `closes #issue_number` into its description for automation
+6.  Collect all these issues into [Project kanbans][22], then create **Pull requests** & add `closes #issue_number` into its description for automation
 
 ## API Usage
 
@@ -64,7 +72,7 @@ pnpm i
 pnpm dev
 ```
 
-or just press <kbd>F5</kbd> key in [VS Code][17].
+or just press <kbd>F5</kbd> key in [VS Code][18].
 
 ### Migration
 
@@ -125,11 +133,11 @@ git push origin master --tags
 [12]: https://typeorm.io/
 [13]: https://swagger.io/
 [14]: https://github.com/anttiviljami/openapi-backend
-[15]: https://github.com/apps/settings
-[16]: https://pullrequestbadge.com/
+[15]: https://github.com/idea2app/Next-SSR-middleware
+[16]: https://github.com/apps/settings
+[17]: https://pullrequestbadge.com/
 [17]: https://code.visualstudio.com/
-[18]: https://github.com/new?template_name=REST-Node-ts&template_owner=idea2app
-[19]: https://github.com/kaiyuanshe/kaiyuanshe.github.io/blob/bb4675a56bf1d6b207231313da5ed0af7cf0ebd6/.github/workflows/pull-request.yml#L32-L56
-[20]: https://github.com/idea2app/REST-Node-ts/issues/new/choose
-[21]: https://github.com/idea2app/REST-Node-ts/projects
-[22]: https://github.com/settings/tokens
+[19]: https://github.com/new?template_name=REST-Node-ts&template_owner=idea2app
+[20]: https://github.com/kaiyuanshe/kaiyuanshe.github.io/blob/bb4675a56bf1d6b207231313da5ed0af7cf0ebd6/.github/workflows/pull-request.yml#L32-L56
+[21]: https://github.com/idea2app/REST-Node-ts/issues/new/choose
+[22]: https://github.com/idea2app/REST-Node-ts/projects

package.json

@@ -1,6 +1,6 @@
 {
     "name": "@idea2app/rest-node-ts",
-    "version": "0.9.0",
+    "version": "1.0.0",
     "license": "LGPL-3.0",
     "author": "shiy2008@gmail.com",
     "description": "RESTful API service scaffold based on Node.js & TypeScript",
@@ -45,6 +45,7 @@
         "web-utility": "^4.4.0"
     },
     "devDependencies": {
+        "@octokit/openapi-types": "^22.2.0",
         "@types/jsonwebtoken": "^9.0.6",
         "@types/koa": "^2.15.0",
         "@types/koa-logger": "^3.1.5",

source/controller/OAuth.ts

@@ -0,0 +1,34 @@
+import { Body, JsonController, Post } from 'routing-controllers';
+import { ResponseSchema } from 'routing-controllers-openapi';
+import { isDeepStrictEqual } from 'util';
+
+import { dataSource, GitHubUser, OAuthSignInData, User } from '../model';
+import { ActivityLogController } from './ActivityLog';
+import { UserController } from './User';
+
+const store = dataSource.getRepository(User);
+
+@JsonController('/user/OAuth')
+export class OauthController {
+    @Post('/GitHub')
+    @ResponseSchema(User)
+    async signInWithGithub(@Body() { accessToken }: OAuthSignInData) {
+        const response = await fetch('https://api.github.com/user', {
+            headers: { Authorization: `Bearer ${accessToken}` }
+        });
+        const { email, login, avatar_url } =
+            (await response.json()) as GitHubUser;
+        const user =
+            (await store.findOneBy({ email })) ||
+            (await UserController.signUp({ email, password: accessToken }));
+        const newProfile = { name: login, avatar: avatar_url },
+            oldPofile = { name: user.name, avatar: user.avatar };
+
+        if (!isDeepStrictEqual(oldPofile, newProfile)) {
+            await store.update(user.id, newProfile);
+
+            await ActivityLogController.logUpdate(user, 'User', user.id);
+        }
+        return UserController.sign(user);
+    }
+}

source/controller/index.ts

@@ -4,13 +4,20 @@ import { createAPI } from 'koagger';
 import { isProduct } from '../utility';
 import { BaseController } from './Base';
 import { UserController } from './User';
+import { OauthController } from './OAuth';
 import { ActivityLogController } from './ActivityLog';
 
 export * from './Base';
 export * from './User';
+export * from './OAuth';
 export * from './ActivityLog';
 
 export const { swagger, mocker, router } = createAPI({
     mock: !isProduct,
-    controllers: [UserController, ActivityLogController, BaseController]
+    controllers: [
+        OauthController,
+        UserController,
+        ActivityLogController,
+        BaseController
+    ]
 });

source/model/OAuth.ts

@@ -0,0 +1,9 @@
+import { components } from '@octokit/openapi-types';
+import { IsString } from 'class-validator';
+
+export class OAuthSignInData {
+    @IsString()
+    accessToken: string;
+}
+
+export type GitHubUser = components['schemas']['simple-user'];

source/model/index.ts

@@ -8,6 +8,7 @@ import { ActivityLog } from './ActivityLog';
 
 export * from './Base';
 export * from './User';
+export * from './OAuth';
 export * from './ActivityLog';
 
 const { ssl, host, port, user, password, database } = isProduct

type/ReadMe.md

@@ -4,7 +4,7 @@
 
 ### 1. Sign in GitHub packages with NPM
 
-1. Generate a PAT with `read:packages` authorization
+1. Generate a [PAT][1] with `read:packages` authorization
 2. Run Sign-in command in your terminal, and use PAT as password:
     ```shell
     npm login --scope=@idea2app --registry=https://npm.pkg.github.com
@@ -17,3 +17,5 @@ npm i pnpm -g
 
 pnpm i @idea2app/rest-node-ts -D
 ```
+
+[1]: https://github.com/settings/tokens

type/package.json

@@ -1,8 +1,9 @@
 {
     "name": "@idea2app/rest-node-ts",
-    "version": "0.9.0",
+    "version": "1.0.0",
     "types": "index.d.ts",
     "dependencies": {
+        "@octokit/openapi-types": "^22.2.0",
         "@types/jsonwebtoken": "^9.0.6",
         "@types/koa": "^2.15.0",
         "mobx-restful": "^1.0.0"