📝 docs: complete documentation for auth module

src/modules/auth/schemas/githubCallback.schema.ts

@@ -0,0 +1,57 @@
+import { t } from "elysia";
+import { AppRouteSchema } from "../../../helpers/types/AppRouteSchema";
+
+export const githubCallbackSchema = {
+  headers: t.Object({
+    "x-client-info": t.String({
+      examples: [
+        '{"os":"Windows","osVersion":"10","browser":"Chrome","browserVersion":"89.0.4389.82","deviceType":"Desktop","ip":"192.168.1.1"}',
+      ],
+    }),
+  }),
+  query: t.Object({
+    code: t.String({ examples: ["4/0AY0e-xxxxxxxxx"] }),
+    callbackURI: t.String({ examples: ["https://example.com/auth/github/callback"] }),
+  }),
+  detail: {
+    summary: "GitHub OAuth callback endpoint",
+    description:
+      "Handles the callback from GitHub OAuth and processes the authentication response. This endpoint also processes the account provisioning if the user is logging in for the first time.",
+    responses: {
+      200: {
+        description: "Authentication successful",
+        content: {
+          "application/json": {
+            schema: {
+              type: "object",
+              properties: {
+                success: {
+                  type: "boolean",
+                  example: true,
+                },
+                status: {
+                  type: "number",
+                  example: 200,
+                },
+                message: {
+                  type: "string",
+                  example: "Authentication successful",
+                },
+                data: {
+                  type: "object",
+                  properties: {
+                    authToken: {
+                      type: "string",
+                      description: "JWT token for authenticated user",
+                      example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+} satisfies AppRouteSchema;

src/modules/auth/schemas/githubRequest.schema.ts

@@ -0,0 +1,54 @@
+import { t } from "elysia";
+import { AppRouteSchema } from "../../../helpers/types/AppRouteSchema";
+
+export const githubRequestSchema = {
+  query: t.Object({
+    callback: t.Optional(
+      t.String({
+        description: "The callback URL to redirect after GitHub authentication. It should be URL-encoded if provided.",
+      }),
+    ),
+  }),
+  detail: {
+    summary: "Initiate GitHub OAuth flow",
+    description:
+      "This endpoint initiates the GitHub OAuth flow by redirecting the user to GitHub's authentication page.",
+    responses: {
+      200: {
+        description: "GitHub login URL created successfully.",
+        content: {
+          "application/json": {
+            schema: {
+              type: "object",
+              properties: {
+                success: {
+                  type: "boolean",
+                  default: true,
+                },
+                status: {
+                  type: "number",
+                  default: 200,
+                },
+                message: {
+                  type: "string",
+                  default: "GitHub login URL created successfully.",
+                },
+                data: {
+                  type: "object",
+                  properties: {
+                    endpointUrl: {
+                      type: "string",
+                      description: "The URL to redirect the user for GitHub authentication.",
+                      example:
+                        "https://github.com/login/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code&scope=user:email",
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+} satisfies AppRouteSchema;

src/modules/auth/schemas/logout.schema.ts

@@ -0,0 +1,97 @@
+import { AppRouteSchema } from "../../../helpers/types/AppRouteSchema";
+
+export const logoutSchema = {
+  detail: {
+    summary: "Logout endpoint",
+    description: "Logs out the authenticated user by invalidating their session or token.",
+    responses: {
+      200: {
+        description: "Logout successful",
+        content: {
+          "application/json": {
+            schema: {
+              type: "object",
+              properties: {
+                success: {
+                  type: "boolean",
+                  example: true,
+                },
+                status: {
+                  type: "number",
+                  example: 200,
+                },
+                message: {
+                  type: "string",
+                  example: "Logout successful",
+                },
+                data: {
+                  type: "object",
+                  description: "Details about the logout operation. This only returned in development environment.",
+                  properties: {
+                    id: {
+                      type: "string",
+                      example: "123e4567-e89b-12d3-a456-426614174000",
+                    },
+                    isAuthenticated: {
+                      type: "boolean",
+                      example: false,
+                    },
+                    validUntil: {
+                      type: "string",
+                      format: "date-time",
+                      example: "2024-12-31T23:59:59Z",
+                    },
+                    userId: {
+                      type: "string",
+                      example: "user_12345",
+                    },
+                    deletedAt: {
+                      type: "string",
+                      format: "date-time",
+                      example: "2024-01-02T12:00:00Z",
+                    },
+                    createdAt: {
+                      type: "string",
+                      format: "date-time",
+                      example: "2024-01-01T12:00:00Z",
+                    },
+                    updatedAt: {
+                      type: "string",
+                      format: "date-time",
+                      example: "2024-01-02T12:00:00Z",
+                    },
+                    deviceType: {
+                      type: "string",
+                      example: "Desktop",
+                    },
+                    deviceOs: {
+                      type: "string",
+                      example: "Windows 10",
+                    },
+                    deviceIp: {
+                      type: "string",
+                      example: "192.168.1.1",
+                    },
+                    browser: {
+                      type: "string",
+                      example: "Chrome 89.0.4389.82",
+                    },
+                    isOnline: {
+                      type: "boolean",
+                      example: false,
+                    },
+                    lastOnline: {
+                      type: "string",
+                      format: "date-time",
+                      example: "2024-01-02T12:00:00Z",
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+} satisfies AppRouteSchema;