@starklabs/backend-core 1.1.0 → 1.2.0

package/dist/js/core/crud/crud.service.js

@@ -0,0 +1,296 @@
+import { getConfig } from "../../config/config.js";
+import { hash } from "../../utils/libsodium.js";
+import { AppError, uploadFile, deleteFile } from "../../utils/index.js";
+
+const sanitize = (doc) => {
+  if (!doc) return doc;
+  const { __v, password, ...clean } = doc;
+  return clean;
+};
+
+const authorizeAccess = ({ ownerEmail, dataEmail, role }) => {
+  const { internalRoles } = getConfig();
+
+  if (!internalRoles?.length)
+    throw new AppError("internalRoles is missing in StarkCore({})");
+
+  const isInternalRuler = internalRoles.includes(role);
+  const isOwner = ownerEmail === dataEmail;
+
+  if (!isInternalRuler && !isOwner) throw new AppError("Unauthorized", 401);
+};
+
+const assertInternalRole = (role) => {
+  const { internalRoles } = getConfig();
+
+  const isInternalRuler = internalRoles.includes(role);
+  if (!isInternalRuler) throw new AppError("Unauthorized", 401);
+};
+
+const showHealth = () => {
+  return {
+    msg: "All clear!",
+  };
+};
+
+const getAll = async ({ Model, modelName }) => {
+  const data = await Model.find().lean();
+
+  if (!data.length) {
+    throw new AppError(`${modelName} not found`, 404);
+  }
+
+  return {
+    data: data.map(sanitize),
+    msg: "Fetched all successfully",
+  };
+};
+
+const getById = async ({ Model, modelName, id, userData, body }) => {
+  const data = await Model.findById(id).lean();
+
+  if (!data) {
+    throw new AppError(`${modelName} with id ${id} not found`, 404);
+  }
+
+  authorizeAccess({
+    ownerEmail: userData.email,
+    dataEmail: data.email,
+    role: userData.role,
+  });
+
+  return {
+    data: sanitize(data),
+    msg: "Fetched successfully",
+  };
+};
+
+const create = async ({ Model, modelName, userData, body }) => {
+  assertInternalRole(userData.role);
+
+  const { cloudinaryFolderName } = getConfig();
+
+  // if image
+  let imageMetaData = undefined;
+  if (body.image) {
+    imageMetaData = await uploadFile(body.image, cloudinaryFolderName);
+  }
+
+  // if user
+  if (body.email) {
+    const exists = await Model.findOne({ email: body.email });
+    if (exists) {
+      throw new AppError(`${modelName} with this email already exists`, 409);
+    }
+  }
+
+  if (body.password) body.password = await hash(body.password);
+
+  const newItem = await Model.create({
+    ...body,
+    role: "user",
+    imageMetaData,
+  });
+
+  return {
+    data: sanitize(newItem.toObject()),
+    msg: "Created successfully",
+  };
+};
+
+const update = async ({ Model, modelName, id, body, userData }) => {
+  assertInternalRole(userData.role);
+
+  if (body.password) {
+    body.password = await hash(body.password);
+  }
+
+  const existing = await Model.findById(id);
+
+  if (!existing) {
+    throw new AppError(`${modelName} not found for update`, 404);
+  }
+
+  const { cloudinaryFolderName } = getConfig();
+
+  let imageMetaData;
+  if (body.image) {
+    imageMetaData = await uploadFile(body.image, cloudinaryFolderName);
+  }
+
+  try {
+    const replacementDoc = {
+      ...body,
+      ...(imageMetaData && { imageMetaData }),
+    };
+
+    // Prevent storing raw file object/base64/etc.
+    delete replacementDoc.image;
+
+    const updated = await Model.findOneAndReplace({ _id: id }, replacementDoc, {
+      returnDocument: "after",
+    }).lean();
+
+    // Delete old image after successful replacement
+    if (imageMetaData && existing.imageMetaData?.public_id) {
+      await deleteFile(existing.imageMetaData.public_id);
+    }
+
+    return {
+      data: sanitize(updated),
+      msg: "Updated successfully",
+    };
+  } catch (error) {
+    // Rollback newly uploaded image
+    if (imageMetaData?.public_id) {
+      await deleteFile(imageMetaData.public_id).catch(() => {});
+    }
+
+    if (error.message.includes("duplicate key error")) {
+      throw new AppError(`${modelName} with these detail already exists`);
+    }
+
+    throw error;
+  }
+};
+
+const patch = async ({ Model, modelName, id, body, userData }) => {
+  assertInternalRole(userData.role);
+
+  if (body.password) {
+    body.password = await hash(body.password);
+  }
+
+  const existing = await Model.findById(id);
+
+  if (!existing) {
+    throw new AppError(`${modelName} not found for patch`, 404);
+  }
+
+  const { cloudinaryFolderName } = getConfig();
+
+  let imageMetaData;
+  if (body.image) {
+    // Upload new image first
+    imageMetaData = await uploadFile(body.image, cloudinaryFolderName);
+  }
+
+  try {
+    const updated = await Model.findByIdAndUpdate(
+      id,
+      {
+        $set: {
+          ...body,
+          ...(imageMetaData && { imageMetaData }),
+        },
+      },
+      { returnDocument: "after" },
+    ).lean();
+
+    // Delete old image only after successful DB update
+    if (imageMetaData && existing.imageMetaData?.public_id) {
+      await deleteFile(existing.imageMetaData.public_id);
+    }
+
+    return {
+      data: sanitize(updated),
+      msg: "Updated successfully!",
+    };
+  } catch (error) {
+    // Rollback newly uploaded image if DB update fails
+    if (imageMetaData?.public_id) {
+      await deleteFile(imageMetaData.public_id).catch(() => {});
+    }
+
+    if (error.message.includes("duplicate key error")) {
+      throw new AppError(`${modelName} with these detail already exists`);
+    }
+
+    throw error;
+  }
+};
+
+const remove = async ({ Model, modelName, id, userData }) => {
+  assertInternalRole(userData.role);
+
+  const deleted = await Model.findByIdAndDelete(id).lean();
+
+  if (!deleted) {
+    throw new AppError(`${modelName} not found for delete`, 404);
+  }
+
+  return {
+    data: sanitize(deleted),
+    msg: "Deleted successfully",
+  };
+};
+
+const removeFile = async ({
+  Model,
+  modelName,
+  id,
+  userData,
+  fileType,
+  metaDataName,
+}) => {
+  if (!fileType)
+    throw new AppError(
+      `fileType is required in ${modelName.toLowerCase()} collection`,
+    );
+
+  if (!metaDataName)
+    throw new AppError(
+      `metaDataName is required in ${modelName.toLowerCase()} collection`,
+    );
+
+  assertInternalRole(userData.role);
+
+  const item = await Model.findById(id);
+  if (!item) throw new AppError(`${modelName} not found to delete file`);
+
+  if (Object.keys(item[metaDataName]).length === 0)
+    throw new AppError(`${fileType} not found to delete`);
+
+  if (Object.keys(item[metaDataName].toObject()).length === 0)
+    throw new AppError(`${fileType} not found to delete`);
+
+  const deleted = await deleteFile(item[metaDataName].public_id, fileType);
+
+  item[metaDataName] = undefined;
+
+  item.save();
+
+  return {
+    data: item,
+    msg: "File deleted successfully",
+  };
+};
+
+const removeAll = async ({ Model, modelName, id, userData }) => {
+  assertInternalRole(userData.role);
+
+  const deleted = await Model.deleteMany();
+
+  if (!deleted) {
+    throw new AppError(`${modelName} not found for delete`, 404);
+  }
+
+  return {
+    data: sanitize(deleted),
+    msg: "Deleted all successfully",
+  };
+};
+
+// by deleting all, also delete the images from cloudinary 1/1
+
+export default {
+  showHealth,
+  getAll,
+  getById,
+  create,
+  update,
+  patch,
+  remove,
+  removeFile,
+  removeAll,
+};

package/dist/js/core/index.js

@@ -0,0 +1,3 @@
+export { startServer, app } from "./app.js";
+export { default as crud } from "./crud/crud.controller.js";
+export { default as auth } from "./auth/auth.controller.js";

package/dist/js/index.js

@@ -1,66 +1,55 @@
-// connectDB - connects MongoDB database
-import connectDB from "./db.js";
+import { setConfig } from "./config/config.js";
+
+/**
+ * @typedef {Object} StarkCoreConfig
+ * @property {number} port - *Server listening port number*
+ * @property {Array<object>} collections - *Routes detail*
+ * @property {string} apiVersion - *Current API version*
+ * @property {string} jwtSecret - *Used for JSON Web Token functionalities*
+ * @property {boolean} isOffline - *Connects to local MongoDB instance*
+ * @property {string} masterKey - *Used for encryption/decryption operations*
+ * @property {string} ENV - *Current application environment (e.g. development, production)*
+ * @property {string} tokenExpiry - *JWT/token expiration duration*
+ * @property {Array<string>} internalRoles - *List of internal roles with elevated permissions*
+ * @property {string} resendAPIKey - *API key used for Resend email services*
+ * @property {string|number} rateLimitDuration - *Duration for rate limiting window*
+ * @property {number} maxReqLimit - *Maximum allowed requests within rate limit duration*
+ * @property {string} rateLimitMsg - *Message returned when rate limit is exceeded*
+ * @property {string} cloudinaryAPIKey - *Cloudinary API key*
+ * @property {string} cloudinaryCloudName - *Cloudinary cloud name*
+ * @property {string} cloudinaryAPISecret - *Cloudinary API secret*
+ * @property {string} cloudinaryFolderName - *Default Cloudinary folder for uploads*
+ */
+
+class StarkCore {
+  /**
+   * @param {StarkCoreConfig} config
+   */
 
-// seal/unSeal - encrypt and decrypt data
-import { seal, unSeal } from "./utils/libsodium.js";
-import { signJWT, verifyJWT } from "./utils/jwt.js";
-
-class StarkAuth {
-  #_masterKey;
-  #_JWT_SECRET;
-  #_JWT_EXPIRY;
-
-  // constructor - store keys etc.
   constructor(config) {
-    this.#_masterKey = config.MASTER_KEY;
-    this.#_JWT_SECRET = config.JWT_SECRET;
-    this.#_JWT_EXPIRY = config.JWT_EXPIRY;
-  }
-
-  // create - initializes DB and auth instance
-  static async create(config) {
-    await connectDB(config.MONGO_URI, config.DB_NAME);
-    return new StarkAuth(config);
-  }
-
-  // encrypt - encrypts string using master key
-  async encrypt(str) {
-    return seal(str, this.#_masterKey);
-  }
-
-  // decrypt - decrypts string using master key
-  async decrypt(str, nonce, publicKey, securedPrivateKey) {
-    return unSeal(str, nonce, publicKey, securedPrivateKey, this.#_masterKey);
+    setConfig(config);
   }
 
-  // signJWT
-  signJWT(payLoad) {
-    return signJWT(payLoad, this.#_JWT_SECRET, this.#_JWT_EXPIRY);
-  }
+  /**
+   * @param {StarkCoreConfig} config
+   * @returns {StarkCore}
+   */
 
-  // verifyJWT
-  verifyJWT(token) {
-    return verifyJWT(token, this.#_JWT_SECRET);
+  static create(config) {
+    return new StarkCore(config);
   }
 }
 
-export default StarkAuth;
-
-// crypto - exports hashing utilities
-import { generateMasterKey, generateJWTSecret, hash, verifyHash } from "./utils/libsodium.js";
-
-export const crypto = {
-  generateMasterKey,
+export default StarkCore;
+export { startServer } from "./core/index.js";
+export { default as fieldTypes } from "./lib/field.types.js";
+export { default as zodValidations } from "./lib/zod.validations.js";
+export {
+  AppLog,
   generateJWTSecret,
+  generateMasterKey,
   hash,
+  seal,
+  unSeal,
   verifyHash,
-};
-
-// AppError - custom application error class
-export { default as AppError } from "./utils/AppError.js";
-
-// AppLog - structured logging utility
-export { default as AppLog } from "./utils/AppLog.js";
-
-// async handler - AppError in async functions
-export { default as asyncHandler } from "./utils/asyncHandler.js";
+} from "./utils/index.js";

package/dist/js/lib/db.js

@@ -0,0 +1,40 @@
+// module imports
+import mongoose from "mongoose";
+
+import AppLog from "../utils/AppLog.js";
+
+const connectLocally = async () => {
+  await mongoose.connect(`mongodb://localhost:27017/offline-db`);
+  AppLog("check", "db", "Connected to OFFLINE-DB!");
+};
+
+// connecting to db
+/**
+ *
+ * @param {"MONGODB_URI"} uri
+ * @param {"DATABASE_NAME"} database
+ * @param {true | false} NETWORK
+ * @returns
+ */
+const connectDB = async (
+  MONGODB_URI = "",
+  DATABASE_NAME = "starklabs",
+  NETWORK = false,
+) => {
+  const mongodbUri = MONGODB_URI || "mongodb://localhost:27017";
+  try {
+    if (!NETWORK) {
+      await connectLocally();
+      return;
+    }
+
+    await mongoose.connect(`${mongodbUri}/${DATABASE_NAME}`);
+    AppLog("check", "db", "Connected successfully!");
+  } catch (error) {
+    AppLog("X", "db", "Error while connecting!");
+    AppLog("X", "db", error.message);
+  }
+};
+
+// export
+export default connectDB;

package/dist/js/lib/field.types.js

@@ -0,0 +1,174 @@
+import mongoose from "mongoose";
+
+const { ObjectId } = mongoose.Schema.Types;
+
+const requiredString = {
+  type: String,
+  required: true,
+  trim: true,
+};
+
+const optionalString = {
+  type: String,
+  default: "",
+  trim: true,
+};
+
+const requiredUniqueString = {
+  type: String,
+  required: true,
+  unique: true,
+  trim: true,
+};
+
+const email = {
+  type: String,
+  required: true,
+  unique: true,
+  lowercase: true,
+  trim: true,
+};
+
+const password = {
+  type: String,
+  required: true,
+  minlength: 6,
+  select: false,
+};
+
+const requiredNumber = {
+  type: Number,
+  required: true,
+};
+
+const optionalNumber = {
+  type: Number,
+  default: 0,
+};
+
+const booleanTrue = {
+  type: Boolean,
+  default: true,
+};
+
+const booleanFalse = {
+  type: Boolean,
+  default: false,
+};
+
+const dateNow = {
+  type: Date,
+  default: Date.now,
+};
+
+const stringArray = {
+  type: [String],
+  default: [],
+};
+
+const objectArray = {
+  type: [Object],
+  default: [],
+};
+
+const objectId = {
+  type: ObjectId,
+};
+
+const requiredObjectId = {
+  type: ObjectId,
+  required: true,
+};
+
+const userRef = {
+  type: ObjectId,
+  ref: "User",
+};
+
+const requiredUserRef = {
+  type: ObjectId,
+  ref: "User",
+  required: true,
+};
+
+const userRefArray = [
+  {
+    type: ObjectId,
+    ref: "User",
+  },
+];
+
+const timestamps = {
+  createdAt: dateNow,
+  updatedAt: dateNow,
+};
+
+const provider = {
+  type: String,
+  enum: ["local", "google"],
+  default: "local",
+};
+
+const role = {
+  ...requiredString,
+  enum: ["user", ...JSON.parse(process.env.INTERNAL_ROLES || "[]")],
+  default: "user",
+};
+
+const otp = {
+  type: String,
+  required: true,
+};
+
+const otpExpiry = {
+  type: Number,
+  required: true,
+};
+
+const otpCount = {
+  type: Number,
+  required: true,
+  default: 0,
+  max: [10, "OTP verification limit reached. Please try again later."],
+};
+
+const otpStatus = {
+  type: String,
+  enum: ["pending", "verified", "blocked"],
+  default: "pending",
+};
+
+const imageMetaData = {
+  public_id: { type: String, required: false },
+  secure_url: { type: String, required: false },
+  width: { type: Number, required: false },
+  height: { type: Number, required: false },
+};
+
+export default {
+  requiredString,
+  optionalString,
+  requiredUniqueString,
+  email,
+  password,
+  requiredNumber,
+  optionalNumber,
+  booleanTrue,
+  booleanFalse,
+  dateNow,
+  stringArray,
+  objectArray,
+  objectId,
+  requiredObjectId,
+  userRef,
+  requiredUserRef,
+  userRefArray,
+  timestamps,
+  provider,
+  role,
+  otp,
+  otpExpiry,
+  otpCount,
+  otpStatus,
+  imageMetaData,
+};

package/dist/js/lib/model.factory.js

@@ -0,0 +1,19 @@
+import mongoose from "mongoose";
+import buildSchema from "./schema.builder.js";
+import AppLog from "../utils/AppLog.js";
+import AppError from "../utils/AppError.js";
+
+const createModel = (name, definition) => {
+  if (!name) throw new AppError("modelName is required");
+  if (!definition) throw new AppError("mongooseSchema is required");
+
+  const schema = buildSchema(definition);
+
+  if (mongoose.modelNames().includes(name)) {
+    return mongoose.model(name);
+  }
+  AppLog("db", "modelFactory", `${name} model created!`);
+  return mongoose.model(name, schema);
+};
+
+export default createModel;

package/dist/js/lib/model.registry.js

@@ -0,0 +1,4 @@
+// GLOBAL MODEL REGISTRY
+const registerModel = {};
+
+export default registerModel;

package/dist/js/lib/schema.builder.js

@@ -0,0 +1,35 @@
+import mongoose from "mongoose";
+
+const buildSchema = (definition) => {
+  const schemaObject = {};
+
+  for (const key in definition) {
+    const value = definition[key];
+
+    // CASE 1: primitive shorthand (String, Number, etc.)
+    if (
+      typeof value === "string" ||
+      typeof value === "number" ||
+      typeof value === "boolean"
+    ) {
+      schemaObject[key] = { type: value };
+      continue;
+    }
+
+    // CASE 2: already mongoose-style object
+    if (typeof value === "object" && !Array.isArray(value)) {
+      schemaObject[key] = value;
+      continue;
+    }
+
+    // CASE 3: array schema
+    if (Array.isArray(value)) {
+      schemaObject[key] = value;
+      continue;
+    }
+  }
+
+  return new mongoose.Schema(schemaObject, { timestamps: true });
+};
+
+export default buildSchema;