@mustafahmed1997/learnify-backend 1.0.0

package/README.md

@@ -0,0 +1,167 @@
+# @mustafahmed1997/learnify-backend
+
+Shared backend utilities for Learnify microservices: Clerk-based auth/role
+middlewares, error handling utilities, and the Express `Request` type
+augmentation for `req.user` — all importable from the package root.
+
+## Installation
+
+```bash
+npm install @mustafahmed1997/learnify-backend
+```
+
+### Peer dependencies
+
+This package expects the consuming service to provide its own `express` and
+`@clerk/express` installs (so there is a single shared instance of each at
+runtime, and Clerk's request-scoped auth context works correctly):
+
+```bash
+npm install express @clerk/express
+```
+
+## Setup: `clerkMiddleware()` before `checkAuth`
+
+`checkAuth` reads Clerk auth state via `getAuth(req)`, which requires
+`clerkMiddleware()` from `@clerk/express` to have already run on the request:
+
+```ts
+import express from "express";
+import { clerkMiddleware } from "@clerk/express";
+import { checkAuth, checkRole, globalErrorHandler } from "@mustafahmed1997/learnify-backend";
+
+const app = express();
+
+app.use(clerkMiddleware());
+```
+
+## `checkAuth`
+
+Verifies the request is authenticated via Clerk and attaches a typed
+`req.user` (a `ClerkUser`) for downstream handlers.
+
+```ts
+import { checkAuth } from "@mustafahmed1997/learnify-backend";
+
+app.get("/me", checkAuth, (req, res) => {
+  res.json(req.user);
+});
+```
+
+If the request is not authenticated, `checkAuth` responds `401` with
+`{ error: "Unauthenticated. Login first please." }` and does not call `next()`.
+
+## `checkRole`
+
+Authorizes a request based on the role in the Clerk session claims
+(`sessionClaims.userMetadata.role`). Takes an array of allowed roles.
+
+```ts
+import { checkRole } from "@mustafahmed1997/learnify-backend";
+
+app.delete(
+  "/courses/:id",
+  checkRole(["ADMIN", "INSTRUCTOR"]),
+  deleteCourseController,
+);
+```
+
+If the caller's role is not in the allowed list, it responds `403` with
+`{ message: "Unauthorized !!" }` and does not call `next()`.
+
+### Combined route example
+
+```ts
+app.patch(
+  "/users/:id/role",
+  checkAuth,
+  checkRole(["ADMIN"]),
+  updateRoleController,
+);
+```
+
+## `validRoles` and `Role`
+
+```ts
+import { validRoles } from "@mustafahmed1997/learnify-backend";
+import type { Role } from "@mustafahmed1997/learnify-backend";
+
+console.log(validRoles); // ["STUDENT", "INSTRUCTOR", "ADMIN"]
+
+function isValidRole(value: string): value is Role {
+  return (validRoles as readonly string[]).includes(value);
+}
+```
+
+## `AppError`
+
+A typed operational error carrying an HTTP status code.
+
+```ts
+import { AppError } from "@mustafahmed1997/learnify-backend";
+
+if (!course) {
+  throw new AppError("Course not found", 404);
+}
+```
+
+## `globalErrorHandler`
+
+Express error-handling middleware. Register it **last**, after all routes:
+
+```ts
+import { globalErrorHandler } from "@mustafahmed1997/learnify-backend";
+
+app.use(globalErrorHandler);
+```
+
+- An `AppError` produces `{ error: err.message }` with `err.statusCode`.
+- Any other thrown value produces `{ error: "Internal server error" }` with
+  status `500`.
+
+## `ClerkUser` and `req.user` typing
+
+Importing anything from this package's root automatically loads the Express
+`Request` augmentation, so `req.user` is typed as `ClerkUser | undefined`
+wherever `express`'s `Request` type is used — no extra `express.d.ts` needed
+in the consuming service.
+
+```ts
+import type { Request, Response } from "express";
+import type { ClerkUser } from "@mustafahmed1997/learnify-backend";
+
+function exampleController(req: Request, res: Response) {
+  const clerkId = req.user?.clerkId;
+  const role = req.user?.userMetadata.role;
+
+  res.json({ clerkId, role });
+}
+```
+
+`ClerkUser` shape:
+
+```ts
+type ClerkUser = {
+  clerkId: string;
+  userMetadata: {
+    role: "STUDENT" | "INSTRUCTOR" | "ADMIN";
+    dbUserId: string;
+  };
+  email?: string;
+  firstName?: string;
+  lastName?: string;
+  imageURL?: string;
+};
+```
+
+## TypeScript usage
+
+The package ships its own `.d.ts` declarations — no `@types` package needed.
+It targets ESM (`"type": "module"`) and expects a `moduleResolution` setting
+that supports package `exports` (e.g. `node16`, `nodenext`, or `bundler`).
+
+## What this package does not do
+
+- Does not depend on Prisma or any database.
+- Does not call the Auth Service (or any other service) over HTTP.
+- Does not manage Clerk session creation — that's handled by `clerkMiddleware()`.

package/dist/constants/validRoles.d.ts

@@ -0,0 +1,2 @@
+export declare const validRoles: readonly ["STUDENT", "INSTRUCTOR", "ADMIN"];
+export type Role = (typeof validRoles)[number];

package/dist/constants/validRoles.js

@@ -0,0 +1,2 @@
+export const validRoles = ["STUDENT", "INSTRUCTOR", "ADMIN"];
+//# sourceMappingURL=validRoles.js.map

package/dist/constants/validRoles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validRoles.js","sourceRoot":"","sources":["../../src/constants/validRoles.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,SAAS,EAAE,YAAY,EAAE,OAAO,CAAU,CAAC"}

package/dist/errors/AppError.d.ts

@@ -0,0 +1,4 @@
+export declare class AppError extends Error {
+    statusCode: number;
+    constructor(message: string, statusCode: number);
+}

package/dist/errors/AppError.js

@@ -0,0 +1,8 @@
+export class AppError extends Error {
+    constructor(message, statusCode) {
+        super(message);
+        this.statusCode = statusCode;
+        Object.setPrototypeOf(this, AppError.prototype);
+    }
+}
+//# sourceMappingURL=AppError.js.map

package/dist/errors/AppError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AppError.js","sourceRoot":"","sources":["../../src/errors/AppError.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,QAAS,SAAQ,KAAK;IAGjC,YAAY,OAAe,EAAE,UAAkB;QAC7C,KAAK,CAAC,OAAO,CAAC,CAAC;QAEf,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAE7B,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;IAClD,CAAC;CACF"}

package/dist/errors/globalErrorHandler.d.ts

@@ -0,0 +1,2 @@
+import { NextFunction, Request, Response } from "express";
+export declare function globalErrorHandler(err: unknown, req: Request, res: Response, next: NextFunction): Response<any, Record<string, any>>;

package/dist/errors/globalErrorHandler.js

@@ -0,0 +1,13 @@
+import { AppError } from "./AppError.js";
+export function globalErrorHandler(err, req, res, next) {
+    console.error(err);
+    if (err instanceof AppError) {
+        return res.status(err.statusCode).json({
+            error: err.message,
+        });
+    }
+    return res.status(500).json({
+        error: "Internal server error",
+    });
+}
+//# sourceMappingURL=globalErrorHandler.js.map

package/dist/errors/globalErrorHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"globalErrorHandler.js","sourceRoot":"","sources":["../../src/errors/globalErrorHandler.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,MAAM,UAAU,kBAAkB,CAChC,GAAY,EACZ,GAAY,EACZ,GAAa,EACb,IAAkB;IAElB,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAEnB,IAAI,GAAG,YAAY,QAAQ,EAAE,CAAC;QAC5B,OAAO,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC;YACrC,KAAK,EAAE,GAAG,CAAC,OAAO;SACnB,CAAC,CAAC;IACL,CAAC;IAED,OAAO,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;QAC1B,KAAK,EAAE,uBAAuB;KAC/B,CAAC,CAAC;AACL,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import "./types/express.js";
+export { checkAuth } from "./middlewares/checkAuth.js";
+export { checkRole } from "./middlewares/checkRole.js";
+export { validRoles } from "./constants/validRoles.js";
+export type { Role } from "./constants/validRoles.js";
+export { AppError } from "./errors/AppError.js";
+export { globalErrorHandler } from "./errors/globalErrorHandler.js";
+export type { ClerkUser } from "./types/ClerkUser.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+import "./types/express.js";
+export { checkAuth } from "./middlewares/checkAuth.js";
+export { checkRole } from "./middlewares/checkRole.js";
+export { validRoles } from "./constants/validRoles.js";
+export { AppError } from "./errors/AppError.js";
+export { globalErrorHandler } from "./errors/globalErrorHandler.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,oBAAoB,CAAC;AAE5B,OAAO,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAEvD,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAGvD,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC"}

package/dist/middlewares/checkAuth.d.ts

@@ -0,0 +1,2 @@
+import { NextFunction, Request, Response } from "express";
+export declare function checkAuth(req: Request, res: Response, next: NextFunction): Promise<Response<any, Record<string, any>> | undefined>;

package/dist/middlewares/checkAuth.js

@@ -0,0 +1,32 @@
+import { getAuth } from "@clerk/express";
+export async function checkAuth(req, res, next) {
+    try {
+        const { isAuthenticated, userId, sessionClaims } = getAuth(req);
+        if (!isAuthenticated || !userId) {
+            return res.status(401).json({
+                error: "Unauthenticated. Login first please.",
+            });
+        }
+        const clerkId = userId;
+        const userMetadata = sessionClaims?.userMetadata;
+        const email = sessionClaims?.email;
+        const firstName = sessionClaims?.firstName;
+        const lastName = sessionClaims?.lastName;
+        const imageURL = sessionClaims?.imageURL;
+        const user = {
+            clerkId,
+            email,
+            firstName,
+            lastName,
+            imageURL,
+            userMetadata,
+        };
+        // Attach user to request
+        req.user = user;
+        next();
+    }
+    catch (error) {
+        next(error);
+    }
+}
+//# sourceMappingURL=checkAuth.js.map

package/dist/middlewares/checkAuth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkAuth.js","sourceRoot":"","sources":["../../src/middlewares/checkAuth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAIzC,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,GAAY,EACZ,GAAa,EACb,IAAkB;IAElB,IAAI,CAAC;QACH,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAEhE,IAAI,CAAC,eAAe,IAAI,CAAC,MAAM,EAAE,CAAC;YAChC,OAAO,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;gBAC1B,KAAK,EAAE,sCAAsC;aAC9C,CAAC,CAAC;QACL,CAAC;QAED,MAAM,OAAO,GAAG,MAAM,CAAC;QACvB,MAAM,YAAY,GAAG,aAAa,EAAE,YAAyC,CAAC;QAC9E,MAAM,KAAK,GAAG,aAAa,EAAE,KAA2B,CAAC;QACzD,MAAM,SAAS,GAAG,aAAa,EAAE,SAA+B,CAAC;QACjE,MAAM,QAAQ,GAAG,aAAa,EAAE,QAA8B,CAAC;QAC/D,MAAM,QAAQ,GAAG,aAAa,EAAE,QAA8B,CAAC;QAE/D,MAAM,IAAI,GAAc;YACtB,OAAO;YACP,KAAK;YACL,SAAS;YACT,QAAQ;YACR,QAAQ;YACR,YAAY;SACb,CAAC;QAEF,yBAAyB;QACzB,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;QAEhB,IAAI,EAAE,CAAC;IACT,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,KAAK,CAAC,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/middlewares/checkRole.d.ts

@@ -0,0 +1,3 @@
+import { NextFunction, Request, Response } from "express";
+import { validRoles } from "../constants/validRoles.js";
+export declare function checkRole(roles: (typeof validRoles)[number][]): (req: Request, res: Response, next: NextFunction) => Promise<Response<any, Record<string, any>> | undefined>;

package/dist/middlewares/checkRole.js

@@ -0,0 +1,12 @@
+import { getAuth } from "@clerk/express";
+export function checkRole(roles) {
+    return async (req, res, next) => {
+        const { sessionClaims } = getAuth(req);
+        const userMetaData = sessionClaims?.userMetadata;
+        const role = userMetaData?.role;
+        if (!roles.includes(role))
+            return res.status(403).json({ message: "Unauthorized !!" });
+        next();
+    };
+}
+//# sourceMappingURL=checkRole.js.map

package/dist/middlewares/checkRole.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkRole.js","sourceRoot":"","sources":["../../src/middlewares/checkRole.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAIzC,MAAM,UAAU,SAAS,CAAC,KAAoC;IAC5D,OAAO,KAAK,EAAE,GAAY,EAAE,GAAa,EAAE,IAAkB,EAAE,EAAE;QAC/D,MAAM,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QACvC,MAAM,YAAY,GAAG,aAAa,EAAE,YAGnC,CAAC;QACF,MAAM,IAAI,GAAG,YAAY,EAAE,IAAmC,CAAC;QAE/D,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;YACvB,OAAO,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,iBAAiB,EAAE,CAAC,CAAC;QAE9D,IAAI,EAAE,CAAC;IACT,CAAC,CAAC;AACJ,CAAC"}

package/dist/types/ClerkUser.d.ts

@@ -0,0 +1,12 @@
+import { validRoles } from "../constants/validRoles.js";
+export type ClerkUser = {
+    clerkId: string;
+    userMetadata: {
+        role: (typeof validRoles)[number];
+        dbUserId: string;
+    };
+    email?: string;
+    firstName?: string;
+    lastName?: string;
+    imageURL?: string;
+};

package/dist/types/ClerkUser.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ClerkUser.js.map

package/dist/types/ClerkUser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClerkUser.js","sourceRoot":"","sources":["../../src/types/ClerkUser.ts"],"names":[],"mappings":""}

package/dist/types/express.d.ts

@@ -0,0 +1,9 @@
+import type { ClerkUser } from "./ClerkUser.js";
+declare global {
+    namespace Express {
+        interface Request {
+            user?: ClerkUser;
+        }
+    }
+}
+export {};

package/dist/types/express.js

@@ -0,0 +1,8 @@
+// types/express.ts
+//
+// Augments the global Express namespace so `req.user` is typed everywhere.
+// This must be a real module (imported for its side effect from index.ts,
+// not merely referenced) so the augmentation survives declaration emission
+// and is automatically loaded by any consumer importing from the package root.
+export {};
+//# sourceMappingURL=express.js.map

package/dist/types/express.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.js","sourceRoot":"","sources":["../../src/types/express.ts"],"names":[],"mappings":"AAAA,mBAAmB;AACnB,EAAE;AACF,2EAA2E;AAC3E,0EAA0E;AAC1E,2EAA2E;AAC3E,+EAA+E"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@mustafahmed1997/learnify-backend",
+  "version": "1.0.0",
+  "description": "Shared Clerk-based auth middlewares, role checking, error utilities, and Express types for Learnify backend microservices.",
+  "keywords": [
+    "express",
+    "clerk",
+    "middleware",
+    "learnify"
+  ],
+  "license": "ISC",
+  "author": "Mostafa Ahmed",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mustafaahmed-f/learnify-backend-package.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "peerDependencies": {
+    "@clerk/express": "^1.7.74",
+    "express": "^5.1.0"
+  },
+  "devDependencies": {
+    "@clerk/express": "^1.7.74",
+    "@types/express": "^5.0.3",
+    "@types/node": "^20.19.39",
+    "express": "^5.1.0",
+    "typescript": "^5.1.6",
+    "vitest": "^3.0.0"
+  }
+}