Default Adapter

The default adapter implements user information using MongoDB to store users, invitations, and preferences.

Features

• User Creation, Deletion, Update and List
  • Create Users with emails, passwords and typeIds
    • User TypeId controls their access to the platform
• Email validation, password reset
  • Send validation emails that interface with your front end
  • Send reset password emails
• User invitations
  • Send user invitation emails
• User attachment management
  • Upload, manage and download user file attachments
• User following management
  • Follow and unfollow users, and get their list of followers

Installation

1. Prerequisites

Dependency	Version
node	18+
MongoDB	5+
Nodeblocks Auth Service	3.0.0+
Nodeblocks Organization Service	1.9.1+

2. Install Package

Create your repository and add this package as a dependency

mkdir my-user-service
npx gts init -y
npm install --save @basaldev/blocks-user-service

You will need to also set up your environment variables. Look at Quick Start Guide for a sample.

3. Initial code

info

This example uses cookies authorization.

authenticate: security.defaultCookieAuth, // <-- Cookie authorization

info

This example enables CORS whitelist for localhost. You can add your own domains to the array.

corsOptions: {
  credentials: true,
  origin: ['http://localhost', 'http://your-domain.com'],
},

Place the following into src/index.ts:

import 'dotenv/config';
import {
  createNodeblocksUserApp,
  defaultAdapter,
} from '@basaldev/blocks-user-service';
import {security, crypto} from '@basaldev/blocks-backend-sdk';
import {getEnvBool, getEnvString} from './helper/utilities';

async function main() {
  const adapterOptions: defaultAdapter.UserDefaultAdapterOptions = {
    authEncSecret: getEnvString('AUTH_ENC_SECRET', ''),
    authSignSecret: getEnvString('AUTH_SIGN_SECRET', ''),
    authenticate: security.defaultCookieAuth,
    emailConfig: {
      inviteUser: {
        enabled: getEnvBool('INVITE_USER', false),
      },
      sendResetPasswordEmail: {
        customerTemplate: {
          bodyTemplate: '<p>Password Reset: <a href="\${url}">\${url}</a></p>',
          subject: 'Password Reset',
          urlTemplate:
            'https://your-domain.com/auth/reset-password-submit/${token}',
        },
        enabled: getEnvBool('SEND_PASSWORD_RESET_EMAIL', false),
      },
      sender: getEnvString('SENDER', 'noreply@basal.dev'),
      verifyEmail: {
        customerTemplate: {
          bodyTemplate: '<p>Verify Email: <a href="\${url}">\${url}</a></p>',
          subject: 'Verify Email',
          urlTemplate:
            'https://your-domain.com/auth/verify-email-success/${token}',
        },
        enabled: getEnvBool('VERIFY_EMAIL', false),
      },
      verifyChangeEmail: {
        customerTemplate: {
          bodyTemplate: '<p>Verify Change Email: <a href="\${url}">\${url}</a></p>',
          subject: 'Verify Change Email',
          urlTemplate:
            'https://your-domain.com/settings/verify-change-email-success/${token}',
        },
        enabled: getEnvBool('VERIFY_CHANGE_EMAIL', false),
      },
      deactivateUser: {
        template: {
          bodyTemplate: '<p>Deactivate user</p>',
          subject: 'Deactivate User',
          urlTemplate: '',
        },
        enabled: getEnvBool('DEACTIVATE_USER_EMAIL', false),
      },
    },
  };

  const adapter = await defaultAdapter.createUserDefaultAdapter(adapterOptions, {
    authAPI: getEnvString('AUTH_ENDPOINT', ''),
    db: getEnvString('DATABASE_URL', ''),
    bucket: getEnvString('BUCKET_NAME', ''),
    organizationAPI: getEnvString('ORGANIZATION_ENDPOINT', ''),
    mailService: {
      sendGridApiKey: getEnvString('SENDGRID_API_KEY', ''),
    },
  });

  const app = createNodeblocksUserApp({
    enableCookieParser: true,
    corsOptions: {
      credentials: true,
      origin: ['http://localhost'],
    },
  });

  await app.startService({
    PORT: Number(getEnvString('PORT')),
    adapter,
    env: 'development',
  });
}

void main();

Email verification

For safety reasons, users must verify via email before they can use the platform.

By default, when a user creates a new account via POST /users, the emailVerified field will be false, and the system will send an email to their email address. This email will contain a URL containing a one-time use token. If this valid token is used to hit the /verify-email endpoint, then the service will set emailVerified to true.

On the Tanty sample project, the following workflow occurs:

1. The user hits POST /users endpoint to create an account.
2. This adapter sends an email to their registered email address containing a link to the /waiting-for-verify page on Tanty's frontend as well as the one-time token.
3. The frontend uses this one time token to send a request to POST /verify-email on the user service.
4. The user service validates this token, and sets emailVerified=true for this user.

For more details on this service's endpoints, please consult the OpenAPI document.

API Reference

• TSDoc
• OpenAPI