feat(api): Expose the update user API in the openapi specs

3 files changed, 254 insertions, 0 deletions

diff --git a/packages/open-api/index.ts b/packages/open-api/index.ts
index 057a823f..6f14807d 100644
--- a/packages/open-api/index.ts
+++ b/packages/open-api/index.ts
@@ -5,6 +5,7 @@ import {
   OpenAPIRegistry,
 } from "@asteasolutions/zod-to-openapi";
 
+import { registry as adminRegistry } from "./lib/admin";
 import { registry as assetsRegistry } from "./lib/assets";
 import { registry as bookmarksRegistry } from "./lib/bookmarks";
 import { registry as commonRegistry } from "./lib/common";
@@ -22,6 +23,7 @@ function getOpenApiDocumentation() {
     highlightsRegistry,
     userRegistry,
     assetsRegistry,
+    adminRegistry,
   ]);
 
   const generator = new OpenApiGeneratorV3(registry.definitions);
diff --git a/packages/open-api/karakeep-openapi-spec.json b/packages/open-api/karakeep-openapi-spec.json
index ac74abbf..69bf27f7 100644
--- a/packages/open-api/karakeep-openapi-spec.json
+++ b/packages/open-api/karakeep-openapi-spec.json
@@ -3281,6 +3281,158 @@
           }
         }
       }
+    },
+    "/admin/users/{userId}": {
+      "put": {
+        "description": "Update a user's role, bookmark quota, or storage quota. Admin access required.",
+        "summary": "Update user",
+        "tags": [
+          "Admin"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "description": "The ID of the user to update",
+              "example": "user_123"
+            },
+            "required": true,
+            "name": "userId",
+            "in": "path"
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "role": {
+                    "type": "string",
+                    "enum": [
+                      "user",
+                      "admin"
+                    ]
+                  },
+                  "bookmarkQuota": {
+                    "type": "integer",
+                    "nullable": true,
+                    "minimum": 0
+                  },
+                  "storageQuota": {
+                    "type": "integer",
+                    "nullable": true,
+                    "minimum": 0
+                  }
+                },
+                "description": "User update data",
+                "example": {
+                  "role": "admin",
+                  "bookmarkQuota": 1000,
+                  "storageQuota": 5000000000
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "User updated successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "success": {
+                      "type": "boolean"
+                    }
+                  },
+                  "required": [
+                    "success"
+                  ]
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request - Invalid input data or cannot update own user",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "error"
+                  ]
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthorized - Authentication required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "error"
+                  ]
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Forbidden - Admin access required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "error"
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "User not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "error"
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
     }
   }
 }
\ No newline at end of file
diff --git a/packages/open-api/lib/admin.ts b/packages/open-api/lib/admin.ts
new file mode 100644
index 00000000..80f786f3
--- /dev/null
+++ b/packages/open-api/lib/admin.ts
@@ -0,0 +1,100 @@
+import {
+  extendZodWithOpenApi,
+  OpenAPIRegistry,
+} from "@asteasolutions/zod-to-openapi";
+import { z } from "zod";
+
+import { updateUserSchema } from "@karakeep/shared/types/admin";
+
+import { BearerAuth } from "./common";
+
+export const registry = new OpenAPIRegistry();
+extendZodWithOpenApi(z);
+
+const updateUserRequestSchema = updateUserSchema.omit({ userId: true });
+
+const updateUserResponseSchema = z.object({
+  success: z.boolean(),
+});
+
+registry.registerPath({
+  method: "put",
+  path: "/admin/users/{userId}",
+  description:
+    "Update a user's role, bookmark quota, or storage quota. Admin access required.",
+  summary: "Update user",
+  tags: ["Admin"],
+  security: [{ [BearerAuth.name]: [] }],
+  request: {
+    params: z.object({
+      userId: z.string().openapi({
+        description: "The ID of the user to update",
+        example: "user_123",
+      }),
+    }),
+    body: {
+      content: {
+        "application/json": {
+          schema: updateUserRequestSchema.openapi({
+            description: "User update data",
+            example: {
+              role: "admin",
+              bookmarkQuota: 1000,
+              storageQuota: 5000000000,
+            },
+          }),
+        },
+      },
+    },
+  },
+  responses: {
+    200: {
+      description: "User updated successfully",
+      content: {
+        "application/json": {
+          schema: updateUserResponseSchema,
+        },
+      },
+    },
+    400: {
+      description: "Bad request - Invalid input data or cannot update own user",
+      content: {
+        "application/json": {
+          schema: z.object({
+            error: z.string(),
+          }),
+        },
+      },
+    },
+    401: {
+      description: "Unauthorized - Authentication required",
+      content: {
+        "application/json": {
+          schema: z.object({
+            error: z.string(),
+          }),
+        },
+      },
+    },
+    403: {
+      description: "Forbidden - Admin access required",
+      content: {
+        "application/json": {
+          schema: z.object({
+            error: z.string(),
+          }),
+        },
+      },
+    },
+    404: {
+      description: "User not found",
+      content: {
+        "application/json": {
+          schema: z.object({
+            error: z.string(),
+          }),
+        },
+      },
+    },
+  },
+});