From 7954885f69d8c3adb2f3f78562d00f4dea784605 Mon Sep 17 00:00:00 2001
From: Victor <vdiaz03@uoc.edu>
Date: Tue, 23 Jun 2026 20:42:15 -0400
Subject: [PATCH] docs: add user service JSDoc

---
 apps/api/src/routes/users.ts         |  9 ++++-----
 apps/api/src/services/userService.ts | 28 ++++++++++++++++++++++++++++
 2 files changed, 32 insertions(+), 5 deletions(-)
 create mode 100644 apps/api/src/services/userService.ts

diff --git a/apps/api/src/routes/users.ts b/apps/api/src/routes/users.ts
index 8d7f6d2ee4..a071eccfa6 100644
--- a/apps/api/src/routes/users.ts
+++ b/apps/api/src/routes/users.ts
@@ -1,20 +1,19 @@
 import { Router } from "express";
 
+import { createUser, listUsers } from "../services/userService";
+
 const router = Router();
 
 router.get("/", (_req, res) => {
   res.json({
-    data: [],
+    data: listUsers(),
     message: "User listing is not implemented yet."
   });
 });
 
 router.post("/", (req, res) => {
   res.status(201).json({
-    data: {
-      id: "stub-user-id",
-      ...req.body
-    },
+    data: createUser(req.body),
     message: "User creation is not implemented yet."
   });
 });
diff --git a/apps/api/src/services/userService.ts b/apps/api/src/services/userService.ts
new file mode 100644
index 0000000000..d93c25be34
--- /dev/null
+++ b/apps/api/src/services/userService.ts
@@ -0,0 +1,28 @@
+export type CreateUserInput = Record<string, unknown>;
+
+export type UserRecord = {
+  id: string;
+} & CreateUserInput;
+
+/**
+ * Returns the current user list.
+ *
+ * This service is a placeholder until persistence is added, so callers receive
+ * an empty collection while the route contract remains stable.
+ */
+export function listUsers(): UserRecord[] {
+  return [];
+}
+
+/**
+ * Builds a stub user record from the submitted request body.
+ *
+ * The generated ID makes the create-user route behave like a successful
+ * creation endpoint without requiring a database connection yet.
+ */
+export function createUser(input: CreateUserInput): UserRecord {
+  return {
+    id: "stub-user-id",
+    ...input
+  };
+}