refactor(api): ♻️ Refactor roles, SSO and timelines to new OpenAPI route format

api/api/v1/roles/:id/index.ts

@@ -1,8 +1,9 @@
-import { apiRoute, applyConfig, auth, handleZodError } from "@/api";
+import { apiRoute, applyConfig, auth } from "@/api";
-import { zValidator } from "@hono/zod-validator";
+import { createRoute } from "@hono/zod-openapi";
 import { z } from "zod";
 import { RolePermissions } from "~/drizzle/schema";
 import { Role } from "~/packages/database-interface/role";
+import { ErrorSchema } from "~/types/api";
 
 export const meta = applyConfig({
     allowedMethods: ["GET", "POST", "DELETE"],
@@ -28,13 +29,107 @@ export const schemas = {
         id: z.string().uuid(),
     }),
 };
-export default apiRoute((app) =>
+
-    app.on(
+const routeGet = createRoute({
-        meta.allowedMethods,
+    method: "get",
-        meta.route,
+    path: "/api/v1/roles/{id}",
-        zValidator("param", schemas.param, handleZodError),
+    summary: "Get role data",
-        auth(meta.auth, meta.permissions),
+    middleware: [auth(meta.auth)],
-        async (context) => {
+    request: {
+        params: schemas.param,
+    },
+    responses: {
+        200: {
+            description: "Role",
+            content: {
+                "application/json": {
+                    schema: Role.schema,
+                },
+            },
+        },
+        401: {
+            description: "Unauthorized",
+            content: {
+                "application/json": {
+                    schema: ErrorSchema,
+                },
+            },
+        },
+        404: {
+            description: "Role not found",
+            content: {
+                "application/json": {
+                    schema: ErrorSchema,
+                },
+            },
+        },
+    },
+});
+
+const routePost = createRoute({
+    method: "post",
+    path: "/api/v1/roles/{id}",
+    summary: "Assign role to user",
+    middleware: [auth(meta.auth, meta.permissions)],
+    request: {
+        params: schemas.param,
+    },
+    responses: {
+        204: {
+            description: "Role assigned",
+        },
+        401: {
+            description: "Unauthorized",
+            content: {
+                "application/json": {
+                    schema: ErrorSchema,
+                },
+            },
+        },
+        403: {
+            description: "Forbidden",
+            content: {
+                "application/json": {
+                    schema: ErrorSchema,
+                },
+            },
+        },
+    },
+});
+
+const routeDelete = createRoute({
+    method: "delete",
+    path: "/api/v1/roles/{id}",
+    summary: "Remove role from user",
+    middleware: [auth(meta.auth, meta.permissions)],
+    request: {
+        params: schemas.param,
+    },
+    responses: {
+        204: {
+            description: "Role removed",
+        },
+        401: {
+            description: "Unauthorized",
+            content: {
+                "application/json": {
+                    schema: ErrorSchema,
+                },
+            },
+        },
+        403: {
+            description: "Forbidden",
+            content: {
+                "application/json": {
+                    schema: ErrorSchema,
+                },
+            },
+        },
+    },
+});
+
+export default apiRoute((app) => {
+    app.openapi(routeGet, async (context) => {
         const { user } = context.get("auth");
         const { id } = context.req.valid("param");
 
@@ -42,26 +137,32 @@ export default apiRoute((app) =>
             return context.json({ error: "Unauthorized" }, 401);
         }
 
-            const userRoles = await Role.getUserRoles(
-                user.id,
-                user.data.isAdmin,
-            );
         const role = await Role.fromId(id);
 
         if (!role) {
             return context.json({ error: "Role not found" }, 404);
         }
 
-            switch (context.req.method) {
+        return context.json(role.toApi(), 200);
-                case "GET": {
+    });
-                    return context.json(role.toApi());
+
+    app.openapi(routePost, async (context) => {
+        const { user } = context.get("auth");
+        const { id } = context.req.valid("param");
+
+        if (!user) {
+            return context.json({ error: "Unauthorized" }, 401);
+        }
+
+        const userRoles = await Role.getUserRoles(user.id, user.data.isAdmin);
+        const role = await Role.fromId(id);
+
+        if (!role) {
+            return context.json({ error: "Role not found" }, 404);
         }
 
-                case "POST": {
         const userHighestRole = userRoles.reduce((prev, current) =>
-                        prev.data.priority > current.data.priority
+            prev.data.priority > current.data.priority ? prev : current,
-                            ? prev
-                            : current,
         );
 
         if (role.data.priority > userHighestRole.data.priority) {
@@ -76,12 +177,25 @@ export default apiRoute((app) =>
         await role.linkUser(user.id);
 
         return context.newResponse(null, 204);
+    });
+
+    app.openapi(routeDelete, async (context) => {
+        const { user } = context.get("auth");
+        const { id } = context.req.valid("param");
+
+        if (!user) {
+            return context.json({ error: "Unauthorized" }, 401);
         }
-                case "DELETE": {
+
+        const userRoles = await Role.getUserRoles(user.id, user.data.isAdmin);
+        const role = await Role.fromId(id);
+
+        if (!role) {
+            return context.json({ error: "Role not found" }, 404);
+        }
+
         const userHighestRole = userRoles.reduce((prev, current) =>
-                        prev.data.priority > current.data.priority
+            prev.data.priority > current.data.priority ? prev : current,
-                            ? prev
-                            : current,
         );
 
         if (role.data.priority > userHighestRole.data.priority) {
@@ -96,8 +210,5 @@ export default apiRoute((app) =>
         await role.unlinkUser(user.id);
 
         return context.newResponse(null, 204);
-                }
+    });
-            }
+});
-        },
-    ),
-);

api/api/v1/roles/index.ts

@@ -1,5 +1,7 @@
 import { apiRoute, applyConfig, auth } from "@/api";
+import { createRoute, z } from "@hono/zod-openapi";
 import { Role } from "~/packages/database-interface/role";
+import { ErrorSchema } from "~/types/api";
 
 export const meta = applyConfig({
     allowedMethods: ["GET"],
@@ -13,24 +15,44 @@ export const meta = applyConfig({
     route: "/api/v1/roles",
 });
 
+const route = createRoute({
+    method: "get",
+    path: "/api/v1/roles",
+    summary: "Get user roles",
+    middleware: [auth(meta.auth)],
+    responses: {
+        200: {
+            description: "User roles",
+            content: {
+                "application/json": {
+                    schema: z.array(Role.schema),
+                },
+            },
+        },
+        401: {
+            description: "Unauthorized",
+            content: {
+                "application/json": {
+                    schema: ErrorSchema,
+                },
+            },
+        },
+    },
+});
+
 export default apiRoute((app) =>
-    app.on(
+    app.openapi(route, async (context) => {
-        meta.allowedMethods,
-        meta.route,
-        auth(meta.auth, meta.permissions),
-        async (context) => {
         const { user } = context.get("auth");
 
         if (!user) {
             return context.json({ error: "Unauthorized" }, 401);
         }
 
-            const userRoles = await Role.getUserRoles(
+        const userRoles = await Role.getUserRoles(user.id, user.data.isAdmin);
-                user.id,
-                user.data.isAdmin,
-            );
 
-            return context.json(userRoles.map((r) => r.toApi()));
+        return context.json(
-        },
+            userRoles.map((r) => r.toApi()),
-    ),
+            200,
+        );
+    }),
 );

api/api/v1/sso/:id/index.ts

@@ -1,11 +1,12 @@
-import { apiRoute, applyConfig, auth, handleZodError } from "@/api";
+import { apiRoute, applyConfig, auth } from "@/api";
 import { proxyUrl } from "@/response";
-import { zValidator } from "@hono/zod-validator";
+import { createRoute } from "@hono/zod-openapi";
 import { eq } from "drizzle-orm";
 import { z } from "zod";
 import { db } from "~/drizzle/db";
 import { OpenIdAccounts, RolePermissions } from "~/drizzle/schema";
 import { config } from "~/packages/config-manager";
+import { ErrorSchema } from "~/types/api";
 
 export const meta = applyConfig({
     allowedMethods: ["GET", "DELETE"],
@@ -28,18 +29,79 @@ export const schemas = {
     }),
 };
 
-/**
+const routeGet = createRoute({
- * SSO Account Linking management endpoint
+    method: "get",
- * A GET request allows the user to list all their linked accounts
+    path: "/api/v1/sso/{id}",
- * A POST request allows the user to link a new account
+    summary: "Get linked account",
- */
+    middleware: [auth(meta.auth, meta.permissions)],
-export default apiRoute((app) =>
+    request: {
-    app.on(
+        params: schemas.param,
-        meta.allowedMethods,
+    },
-        meta.route,
+    responses: {
-        zValidator("param", schemas.param, handleZodError),
+        200: {
-        auth(meta.auth, meta.permissions),
+            description: "Linked account",
-        async (context) => {
+            content: {
+                "application/json": {
+                    schema: z.object({
+                        id: z.string(),
+                        name: z.string(),
+                        icon: z.string().optional(),
+                    }),
+                },
+            },
+        },
+        401: {
+            description: "Unauthorized",
+            content: {
+                "application/json": {
+                    schema: ErrorSchema,
+                },
+            },
+        },
+        404: {
+            description: "Account not found",
+            content: {
+                "application/json": {
+                    schema: ErrorSchema,
+                },
+            },
+        },
+    },
+});
+
+const routeDelete = createRoute({
+    method: "delete",
+    path: "/api/v1/sso/{id}",
+    summary: "Unlink account",
+    middleware: [auth(meta.auth, meta.permissions)],
+    request: {
+        params: schemas.param,
+    },
+    responses: {
+        204: {
+            description: "Account unlinked",
+        },
+        401: {
+            description: "Unauthorized",
+            content: {
+                "application/json": {
+                    schema: ErrorSchema,
+                },
+            },
+        },
+        404: {
+            description: "Account not found",
+            content: {
+                "application/json": {
+                    schema: ErrorSchema,
+                },
+            },
+        },
+    },
+});
+
+export default apiRoute((app) => {
+    app.openapi(routeGet, async (context) => {
         const { id: issuerId } = context.req.valid("param");
         const { user } = context.get("auth");
 
@@ -47,6 +109,7 @@ export default apiRoute((app) =>
             return context.json({ error: "Unauthorized" }, 401);
         }
 
+        // Check if issuer exists
         const issuer = config.oidc.providers.find(
             (provider) => provider.id === issuerId,
         );
@@ -55,8 +118,6 @@ export default apiRoute((app) =>
             return context.json({ error: "Issuer not found" }, 404);
         }
 
-            switch (context.req.method) {
-                case "GET": {
         // Get all linked accounts
         const account = await db.query.OpenIdAccounts.findFirst({
             where: (account, { eq, and }) =>
@@ -75,13 +136,33 @@ export default apiRoute((app) =>
             );
         }
 
-                    return context.json({
+        return context.json(
+            {
                 id: issuer.id,
                 name: issuer.name,
                 icon: proxyUrl(issuer.icon) || undefined,
+            },
+            200,
+        );
     });
+
+    app.openapi(routeDelete, async (context) => {
+        const { id: issuerId } = context.req.valid("param");
+        const { user } = context.get("auth");
+
+        if (!user) {
+            return context.json({ error: "Unauthorized" }, 401);
         }
-                case "DELETE": {
+
+        // Check if issuer exists
+        const issuer = config.oidc.providers.find(
+            (provider) => provider.id === issuerId,
+        );
+
+        if (!issuer) {
+            return context.json({ error: "Issuer not found" }, 404);
+        }
+
         const account = await db.query.OpenIdAccounts.findFirst({
             where: (account, { eq, and }) =>
                 and(
@@ -104,8 +185,5 @@ export default apiRoute((app) =>
             .where(eq(OpenIdAccounts.id, account.id));
 
         return context.newResponse(null, 204);
-                }
+    });
-            }
+});
-        },
-    ),
-);

api/api/v1/sso/index.ts

@@ -1,8 +1,8 @@
-import { apiRoute, applyConfig, auth, handleZodError, jsonOrForm } from "@/api";
+import { apiRoute, applyConfig, auth, jsonOrForm } from "@/api";
 import { oauthRedirectUri } from "@/constants";
 import { randomString } from "@/math";
 import { proxyUrl } from "@/response";
-import { zValidator } from "@hono/zod-validator";
+import { createRoute } from "@hono/zod-openapi";
 import {
     calculatePKCECodeChallenge,
     discoveryRequest,
@@ -17,6 +17,7 @@ import {
     RolePermissions,
 } from "~/drizzle/schema";
 import { config } from "~/packages/config-manager";
+import { ErrorSchema } from "~/types/api";
 
 export const meta = applyConfig({
     allowedMethods: ["GET", "POST"],
@@ -34,35 +35,101 @@ export const meta = applyConfig({
 });
 
 export const schemas = {
-    json: z
+    json: z.object({
-        .object({
         issuer: z.string(),
-        })
+    }),
-        .partial(),
 };
 
-/**
+const routeGet = createRoute({
- * SSO Account Linking management endpoint
+    method: "get",
- * A GET request allows the user to list all their linked accounts
+    path: "/api/v1/sso",
- * A POST request allows the user to link a new account, and returns a link
+    summary: "Get linked accounts",
- */
+    middleware: [auth(meta.auth)],
-export default apiRoute((app) =>
+    responses: {
-    app.on(
+        200: {
-        meta.allowedMethods,
+            description: "Linked accounts",
-        meta.route,
+            content: {
-        jsonOrForm(),
+                "application/json": {
-        zValidator("json", schemas.json, handleZodError),
+                    schema: z.array(
-        auth(meta.auth, meta.permissions),
+                        z.object({
-        async (context) => {
+                            id: z.string(),
-            const form = context.req.valid("json");
+                            name: z.string(),
+                            icon: z.string().optional(),
+                        }),
+                    ),
+                },
+            },
+        },
+        401: {
+            description: "Unauthorized",
+            content: {
+                "application/json": {
+                    schema: ErrorSchema,
+                },
+            },
+        },
+    },
+});
+
+const routePost = createRoute({
+    method: "post",
+    path: "/api/v1/sso",
+    summary: "Link account",
+    middleware: [auth(meta.auth), jsonOrForm()],
+    request: {
+        body: {
+            content: {
+                "application/json": {
+                    schema: schemas.json,
+                },
+                "multipart/form-data": {
+                    schema: schemas.json,
+                },
+                "application/x-www-form-urlencoded": {
+                    schema: schemas.json,
+                },
+            },
+        },
+    },
+    responses: {
+        200: {
+            description: "Link URL",
+            content: {
+                "application/json": {
+                    schema: z.object({
+                        link: z.string(),
+                    }),
+                },
+            },
+        },
+        401: {
+            description: "Unauthorized",
+            content: {
+                "application/json": {
+                    schema: ErrorSchema,
+                },
+            },
+        },
+        404: {
+            description: "Issuer not found",
+            content: {
+                "application/json": {
+                    schema: ErrorSchema,
+                },
+            },
+        },
+    },
+});
+
+export default apiRoute((app) => {
+    app.openapi(routeGet, async (context) => {
+        // const form = context.req.valid("json");
         const { user } = context.get("auth");
 
         if (!user) {
             return context.json({ error: "Unauthorized" }, 401);
         }
 
-            switch (context.req.method) {
-                case "GET": {
         // Get all linked accounts
         const accounts = await db.query.OpenIdAccounts.findMany({
             where: (User, { eq }) => eq(User.userId, user.id),
@@ -72,8 +139,7 @@ export default apiRoute((app) =>
             accounts
                 .map((account) => {
                     const issuer = config.oidc.providers.find(
-                                    (provider) =>
+                        (provider) => provider.id === account.issuerId,
-                                        provider.id === account.issuerId,
                     );
 
                     if (!issuer) {
@@ -91,23 +157,16 @@ export default apiRoute((app) =>
                 name: string;
                 icon: string | undefined;
             }[],
+            200,
         );
-                }
+    });
-                case "POST": {
-                    if (!form) {
-                        return context.json(
-                            { error: "Missing issuer in form body" },
-                            400,
-                        );
-                    }
 
-                    const { issuer: issuerId } = form;
+    app.openapi(routePost, async (context) => {
+        const { issuer: issuerId } = context.req.valid("json");
+        const { user } = context.get("auth");
 
-                    if (!issuerId) {
+        if (!user) {
-                        return context.json(
+            return context.json({ error: "Unauthorized" }, 401);
-                            { error: "Missing issuer in form body" },
-                            400,
-                        );
         }
 
         const issuer = config.oidc.providers.find(
@@ -115,10 +174,7 @@ export default apiRoute((app) =>
         );
 
         if (!issuer) {
-                        return context.json(
+            return context.json({ error: `Issuer ${issuerId} not found` }, 404);
-                            { error: `Issuer ${issuerId} not found` },
-                            404,
-                        );
         }
 
         const issuerUrl = new URL(issuer.url);
@@ -154,13 +210,12 @@ export default apiRoute((app) =>
                 .returning()
         )[0];
 
-                    const codeChallenge =
+        const codeChallenge = await calculatePKCECodeChallenge(codeVerifier);
-                        await calculatePKCECodeChallenge(codeVerifier);
 
-                    return context.json({
+        return context.json(
-                        link: `${
+            {
-                            authServer.authorization_endpoint
+                link: `${authServer.authorization_endpoint}?${new URLSearchParams(
-                        }?${new URLSearchParams({
+                    {
                         client_id: issuer.client_id,
                         redirect_uri: `${oauthRedirectUri(
                             issuerId,
@@ -174,10 +229,10 @@ export default apiRoute((app) =>
                         // PKCE
                         code_challenge_method: "S256",
                         code_challenge: codeChallenge,
-                        }).toString()}`,
-                    });
-                }
-            }
                     },
-    ),
+                ).toString()}`,
+            },
+            200,
         );
+    });
+});

api/api/v1/timelines/home.ts

@@ -1,15 +1,11 @@
-import {
+import { apiRoute, applyConfig, auth, idValidator } from "@/api";
-    apiRoute,
+import { createRoute } from "@hono/zod-openapi";
-    applyConfig,
-    auth,
-    handleZodError,
-    idValidator,
-} from "@/api";
-import { zValidator } from "@hono/zod-validator";
 import { and, eq, gt, gte, lt, or, sql } from "drizzle-orm";
 import { z } from "zod";
 import { Notes, RolePermissions } from "~/drizzle/schema";
+import { Note } from "~/packages/database-interface/note";
 import { Timeline } from "~/packages/database-interface/timeline";
+import { ErrorSchema } from "~/types/api";
 
 export const meta = applyConfig({
     allowedMethods: ["GET"],
@@ -40,15 +36,37 @@ export const schemas = {
     }),
 };
 
+const route = createRoute({
+    method: "get",
+    path: "/api/v1/timelines/home",
+    summary: "Get home timeline",
+    middleware: [auth(meta.auth, meta.permissions)],
+    request: {
+        query: schemas.query,
+    },
+    responses: {
+        200: {
+            description: "Home timeline",
+            content: {
+                "application/json": {
+                    schema: z.array(Note.schema),
+                },
+            },
+        },
+        401: {
+            description: "Unauthorized",
+            content: {
+                "application/json": {
+                    schema: ErrorSchema,
+                },
+            },
+        },
+    },
+});
+
 export default apiRoute((app) =>
-    app.on(
+    app.openapi(route, async (context) => {
-        meta.allowedMethods,
+        const { max_id, since_id, min_id, limit } = context.req.valid("query");
-        meta.route,
-        zValidator("query", schemas.query, handleZodError),
-        auth(meta.auth, meta.permissions),
-        async (context) => {
-            const { max_id, since_id, min_id, limit } =
-                context.req.valid("query");
 
         const { user } = context.get("auth");
 
@@ -76,14 +94,11 @@ export default apiRoute((app) =>
         );
 
         return context.json(
-                await Promise.all(
+            await Promise.all(objects.map(async (note) => note.toApi(user))),
-                    objects.map(async (note) => note.toApi(user)),
-                ),
             200,
             {
                 Link: link,
             },
         );
-        },
+    }),
-    ),
 );

api/api/v1/timelines/public.ts

@@ -1,15 +1,11 @@
-import {
+import { apiRoute, applyConfig, auth, idValidator } from "@/api";
-    apiRoute,
+import { createRoute } from "@hono/zod-openapi";
-    applyConfig,
-    auth,
-    handleZodError,
-    idValidator,
-} from "@/api";
-import { zValidator } from "@hono/zod-validator";
 import { and, gt, gte, lt, sql } from "drizzle-orm";
 import { z } from "zod";
 import { Notes, RolePermissions } from "~/drizzle/schema";
+import { Note } from "~/packages/database-interface/note";
 import { Timeline } from "~/packages/database-interface/timeline";
+import { ErrorSchema } from "~/types/api";
 
 export const meta = applyConfig({
     allowedMethods: ["GET"],
@@ -51,22 +47,38 @@ export const schemas = {
     }),
 };
 
+const route = createRoute({
+    method: "get",
+    path: "/api/v1/timelines/public",
+    summary: "Get public timeline",
+    middleware: [auth(meta.auth, meta.permissions)],
+    request: {
+        query: schemas.query,
+    },
+    responses: {
+        200: {
+            description: "Public timeline",
+            content: {
+                "application/json": {
+                    schema: z.array(Note.schema),
+                },
+            },
+        },
+        401: {
+            description: "Unauthorized",
+            content: {
+                "application/json": {
+                    schema: ErrorSchema,
+                },
+            },
+        },
+    },
+});
+
 export default apiRoute((app) =>
-    app.on(
+    app.openapi(route, async (context) => {
-        meta.allowedMethods,
+        const { max_id, since_id, min_id, limit, local, remote, only_media } =
-        meta.route,
+            context.req.valid("query");
-        zValidator("query", schemas.query, handleZodError),
-        auth(meta.auth, meta.permissions),
-        async (context) => {
-            const {
-                max_id,
-                since_id,
-                min_id,
-                limit,
-                local,
-                remote,
-                only_media,
-            } = context.req.valid("query");
 
         const { user } = context.get("auth");
 
@@ -94,14 +106,11 @@ export default apiRoute((app) =>
         );
 
         return context.json(
-                await Promise.all(
+            await Promise.all(objects.map(async (note) => note.toApi(user))),
-                    objects.map(async (note) => note.toApi(user)),
-                ),
             200,
             {
                 Link: link,
             },
         );
-        },
+    }),
-    ),
 );