mua-backend v0.3.14

Mua-Backend Documentation and Integration Guide

The mua-backend is a full authentication and user management system designed to integrate seamlessly with the mua-frontend. It enables a Slack-like authentication experience, supporting multiple workspaces where users can log in with shared or separate credentials per workspace.

This backend simplifies the creation and management of accounts, users, and system administrators, providing ready-to-use routes.

Features

• Slack-like Workspace Management: Users can log into separate workspaces, each with its own independent credentials.
• Route Auto-Generation: Automatically generates routes for account, user, and system admin management.
• Flexible API Integration: Built to work with an API server created using the Express Async API.

Getting Started

Installation

Install mua-backend via npm:

npm install mua-backend

Setup

To set up the mua-backend, you need to provide the following parameters:

1. API Server

• An instance created using the express-async-api library.

2. Models

• To ensure smooth integration and customization, it's essential that you pass the following models to the mua-backend. These models define the mandatory properties that are needed for managing accounts, users, and system administrators. You can extend these models by adding additional properties as needed.

• AccountModel: The model for managing workspace accounts.

const AccountSchema = new mongoose.Schema({
  name: { type: String },
  urlFriendlyName: { type: String, unique: true },
  logo: { type: String },
  deleted: { type: Boolean }
}, { timestamps: true })

export default mongoose.model('Account', AccountSchema)

• UserModel: The model for managing users.

const UserSchema = new mongoose.Schema({
  name: { type: String },
  email: { type: String, lowercase: true, required: true, match: /.+[\\@].+\..+/ },
  password: { type: String },
  googleProfileId: { type: String },
  microsoftProfileId: { type: String },
  githubProfileId: { type: String },
  role: { type: String, default: 'user', enum: ['user', 'admin'] },
  accountId: { type: Schema.Types.ObjectId, ref: 'Account', required: true },
  profilePicture: { type: String },
  verified: { type: Boolean, default: false },
  deleted: { type: Boolean }
}, { timestamps: true })

export default mongoose.model('User', UserSchema)

• SystemAdminModel: The model for managing system administrators.

const SystemAdminSchema = new mongoose.Schema({
  name: { type: String },
  email: { type: String, lowercase: true, required: true, match: /.+[\\@].+\..+/, unique: true },
  password: { type: String },
  profilePicture: { type: String }
}, { timestamps: true });

export default mongoose.model('SystemAdmin', SystemAdminSchema)

3. Integration Example

import MuaBackend from'mua-backend' 
import AccountModel from'./models/account' 
import UserModel from'./models/user'
import SystemAdminModel from'./models/systemAdmin' 

MuaBackend({  
  apiServer,  
  AccountModel,
  UserModel,
  SystemAdminModel,
  hooks: {} // optional  
})

4. Add to .env file

You need to provide the following environment variables in a .env file for Mua to function properly.

NODE_ENV=development # Environment mode (e.g., development, production)
SECRETS=testsecret1 testsecret2 # Space-separated list of secrets used for token encryption

APP_URL=<app_url> # The base URL of your application

BLUEFOX_TRANSACTIONAL_EMAIL_API_URL=<emailfox_transactional_url> # URL for the Bluefox transactional email API
BLUEFOX_API_KEY=<bluefox_email_api_key> # API key for Bluefox email service

BLUEFOX_TEMPLATE_ID_ADMIN_VERIFY_EMAIL=<bluefox_template_id> # Bluefox Template ID for admin email verification
BLUEFOX_TEMPLATE_ID_ADMIN_FORGOT_PASSWORD=<bluefox_template_id> # Bluefox Template ID for admin forgot password
BLUEFOX_TEMPLATE_ID_ADMIN_INVITATION=<bluefox_template_id> # Bluefox Template ID for admin invitation
BLUEFOX_TEMPLATE_ID_ACCOUNT_FINALIZE_REGISTRATION=<bluefox_template_id> # Bluefox Template ID for account registration finalization
BLUEFOX_TEMPLATE_ID_ACCOUNT_FORGOT_PASSWORD=<bluefox_template_id> # Bluefox Template ID for account forgot password
BLUEFOX_TEMPLATE_ID_ACCOUNT_INVITATION=<bluefox_template_id> # Bluefox Template ID for account invitation
BLUEFOX_TEMPLATE_ID_ACCOUNT_LOGIN_SELECT=<bluefox_template_id> # Bluefox Template ID for account login selection
BLUEFOX_TEMPLATE_ID_ACCOUNT_VERIFY_EMAIL=<bluefox_template_id> # Bluefox Template ID for account email verification
BLUEFOX_TEMPLATE_ID_ACCOUNT_CREATE_PASSWORD=<bluefox_template_id> # Bluefox Template ID for account password creation

CDN_BASE_URL=<cdn_base_url> # Base URL for your CDN

AWS_BUCKET_PATH=<aws.bucket.path> # Path to the AWS bucket
AWS_BUCKET_NAME=<your_aws_bucket_name> # Name of the AWS S3 bucket
AWS_FOLDER_NAME=<your_aws_folder_name> # Folder name in the AWS S3 bucket
AWS_REGION=<your_aws_region> # AWS region for the S3 bucket
AWS_ACCESS_KEY_ID=<your_aws_access_key_id> # AWS access key ID
AWS_SECRET_ACCESS_KEY=<your_aws_secret_access_key> # AWS secret access key

ALPHA_MODE=false # Enable alpha mode (true/false)
MAX_FILE_SIZE=5242880 # Maximum file upload size in bytes (e.g., 5MB)

GOOGLE_CLIENT_ID=<your_google_client_id> # Google OAuth client ID
GOOGLE_CLIENT_SECRET=<your_google_client_secret> # Google OAuth client secret

MICROSOFT_CLIENT_ID=<your_microsoft_client_id> # Microsoft OAuth client ID
MICROSOFT_CLIENT_SECRET=<your_microsoft_client_secret> # Microsoft OAuth client secret

GITHUB_CLIENT_ID=<your_github_client_id> # GitHub OAuth client ID
GITHUB_CLIENT_SECRET=<your_github_client_secret> # GitHub OAuth client secret

Customization

The mua-backend allows users to customize behavior after specific actions, such as creating or deleting accounts. Pass a hooks object with functions to override default behaviors:

MuaBackend({
  apiServer,
  AccountModel,
  UserModel,
  SystemAdminModel,
  hooks: {
    deleteAccount: {
      post: (params) => {
        // Custom logic after deleting an account
      },
    },
    createAccount: {
      post: (params) => {
        // Custom logic after creating an account
      },
    },
    createNewUser: {
      post: (params) => {
        // Custom logic after creating a new user
      },
    },
    updateUserEmail: {
      post: (params) => {
        // Custom logic after updating a user's email
      },
    },
  },
})

Each hook accepts an object with a post method that executes custom logic after the associated action is completed.

API Routes

Developers using mua can rely on the seamless integration with the mua-frontend, so they don't need to concern themselves with these routes. The table below outlines the automatically generated routes and their purposes:

Accounts routes

System admins routes

Users routes

Auth routes

Provider Auth routes

Forgot password routes

Invitation routes

Statistics routes