hm-login-handler

v1.3.0

Published

2 months ago

### This document contains detailed instructions on "How to Use" the package hm-login-handler.

0High
0Medium
0Low

thehived

vicky-cidroy

hm-login-handler

This document contains detailed instructions on "How to Use" the package hm-login-handler.

1. Steps to install the package in your app:

Go to your project directory in terminal.
Run the following command:

npm i hm-login-handler

If you have built your application using HTML and JavaScript, import the hived-login-handler.min.js file from the dist directory present within the hived-login-handler application root directory as below:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta http-equiv="x-ua-compatible" content="ie=edge" />
    <title>HivedMusic Login (Example App)</title>
    <meta name="viewport" content="width=device-width, initial-scale=1" />

    <script>
      const renderForm = () => {
        hivedLoginHandler.renderHMLoginForm(
          "form-wrapper",
          {
            name: "HivedMusic.com",
            url: "https://www.hivedmusic.com/",
            env: "dev",
            formType: "signup",
          },
          (appRes) => {
            console.log(appRes);
          }
        );
      };

      const removeForm = () => {
        hivedLoginHandler.removeHMLoginForm();
      };

      const openModal = () => {
        hivedLoginHandler.openHMLoginModal(
          {
            name: "HivedMusic.com",
            url: "https://www.hivedmusic.com/",
            env: "dev",
          },
          (appRes) => {
            console.log(appRes);
          }
        );
      };

      const closeModal = () => {
        hivedLoginHandler.closeHMLoginModal();
      };
    </script>
  </head>

  <body>
    <div style="margin: 8px 0;">
      <button onclick="renderForm()">Render Form</button>
      <button onclick="removeForm()">Remove Form</button>
    </div>
    <div style="margin: 8px 0;">
      <button onclick="openModal()">Open Modal</button>
      <button onclick="closeModal()">Close Modal</button>
    </div>

    <div id="form-wrapper"></div>
    <script
      src="/<replace_with_your_path>/hm-login-handler/dist/hm-login-handler.min.js"
      async
      onload="renderForm();"
    ></script>
  </body>
</html>

2. Steps to use the package:

This application can be used in two ways, as a form or as a modal but only one instance of the app can run at a time i.e., only one form can be rendered at a time or a single modal can be opened and it must be closed before opening a new modal.
After installing the package, you can render the form by invoking renderHMLoginForm function. This function must be invoked with three mandatory arguments, first argument must be a string whose value must be the id of the div inside which the form will be rendered, second argument must be an object containing the client details and the third argument must be a callback function which must accept an argument that will contain information about the app event.
This application can also be used as a modal by invoking openHMLoginModal function and close the modal using closeHMLoginModal function respectively.
openHMLoginModal function must be invoked with two mandatory arguments, first argument must be an object containing the client details and the second argument must be a callback function which must accept an argument that will contain information about the app event.
closeHMLoginModal function needs to be called if you want to close the modal.
For detailed instructions on implementing the functions, follow the steps below.

a. Steps to use the app as a form:

Import renderHMLoginForm function using the following piece of code:

import { renderHMLoginForm } from "hm-login-handler";

Create a div with an id attribute:

<div id="form-wrapper"></div>

Invoke renderHMLoginForm function by passing the div's id where the form will be rendered along with other arguments as:

renderHMLoginForm(
  "form-wrapper",
  { name: "HivedMusic.com", url: "https://www.hivedmusic.com", env: "dev" }, // env is optional
  (appRes) => {
    console.log(appRes);
  }
);

b. Steps to use the app as a modal:

Import openHMLoginModal function using the following piece of code:

import { openHMLoginModal } from "hm-login-handler";

Invoke openHMLoginModal function with all the arguments as:

openHMLoginModal(
  { name: "HivedMusic.com", url: "https://www.hivedmusic.com/", env: "dev" }, // env is optional
  (appRes) => {
    console.log(appRes);
  }
);

To close the modal, closeHMLoginModal needs to be invoked. Do not provide any argument to this function.
Import the closeHMLoginModal function using the following piece of code:

import { closeHMLoginModal } from "hm-login-handler";

Invoke closeHMLoginModal function as:

closeHMLoginModal();

Details of the different properties that can be passed with the object as the second argument to renderHMLoginForm or as the first argument to openHMLoginModal:

const clientDetails = {
  name: "string", // required, the client name that will be shown on the modal header e.g., HivedMusic.com
  url: "string", // required, the URL that will be opened on clicking the client name on the modal header
  rid: "string", // optional, if the referral id is available
  tid: "string", // optional, if the tracker id is available
  env: "string", // optional, this is needed only for the purpose of testing. supported values are: dev, beta, prod. if this property is not passed, env will default to prod
};

renderHMLoginForm("form-wrapper", clientDetails, callbackFunction);
// or
openHMLoginModal(clientDetails, callbackFunction);

const callbackFunction = (appResponse) => {
  // handle app response here
};

3. Handling the app events response:

For different events throughout the app creation till the app is removed from the DOM, the callback function that you provided to renderHMLoginForm or openHMLoginModal function will be called along with the event details object as the first argument.
Follow the code below to handle the different app events in your code:

// all app events:
// form rendered
// modal opened
// modal closed
// modal closed by user
// login success
// login failed
// sign-up success
// sign-up failed

// the app event response object looks like this:
const appResObj = {
  app: {
    event: "string",
    message: "string",
  },
  user: {
    token: "string", // activation code (only present for successful login/sign-up events)
  },
};

// note: for all other events except successful login or successful sign-up event, the user token will be null
// IMPORTANT: user.token is an activation code (5-minute expiry) that must be sent to your server
// for validation with HivedMusic service. This activates the widget's internal authentication.

const handleAppResponse = (appRes) => {
  switch (appRes.app.event) {
    case "form rendered":
      // do something after the form is rendered
      break;
    case "modal opened":
      // do something after the modal is opened
      break;
    case "modal closed":
      // do something after the modal is closed
      break;
    case "modal closed by user":
      // do something after the modal is closed by clicking
      // on the modal close button
      break;
    case "login success":
      // access the activation code (5-minute expiry) as below
      const activationCode = appRes.user.token;
      // IMPORTANT: Send this activation code to your server immediately
      // Your server must validate it with HivedMusic service to activate the user session
      console.log(activationCode);
      // do something after the login attempt was successful
      break;
    case "login failed":
      // do something after the login attempt was failed
      break;
    case "sign-up success":
      // access the activation code (5-minute expiry) as below
      const signupActivationCode = appRes.user.token;
      // IMPORTANT: Send this activation code to your server immediately
      // Your server must validate it with HivedMusic service to activate the user session
      console.log(signupActivationCode);
      // do something after the sign-up attempt was successful
      break;
    case "sign-up failed":
    // do something after the sign-up attempt was failed
  }
};

4. Understanding Activation Codes and Authentication Flow:

When a user successfully logs in or signs up, the widget emits an activation code in the user.token field. This activation code serves a critical dual purpose in the authentication system:

What is an Activation Code?

An activation code is a temporary, short-lived token with the following characteristics:

Expires in 5 minutes from the moment it's issued
One-time use only - cannot be reused after validation
Must be validated by your server with HivedMusic service to complete authentication

Authentication Flow:

User Authentication: User successfully logs in or signs up through the widget
Activation Code Issued: Widget receives an activation code from HivedMusic service
Event Callback: Your application receives the activation code via "login success" or "sign-up success" event
Server Validation Required: Your application must immediately send the activation code to your server
Activation with HivedMusic: Your server validates the activation code with HivedMusic service
Widget Activation: Once validated, the widget's internal authentication is activated
Full Functionality: Profile management and other authenticated features become available

Important Notes:

Widget remains inactive until the activation code is validated by your server with HivedMusic service
Profile features will not work until activation is complete
Send activation code immediately to your server to avoid expiry (5-minute limit)
Your server must have API credentials to validate activation codes with HivedMusic service
The widget manages its own internal authentication token automatically after activation

User Profile Feature

Prerequisites: The user profile feature requires that the activation code has been validated by your server with HivedMusic service. The widget's internal authentication must be activated before profile features will function.

The user profile feature provides a user interface for authenticated users to view and edit their profile information, change their password (if applicable), and log out. This feature is implemented as an additive change that preserves backward compatibility with existing code.

Features

Display user profile information (name, email, profile picture)
Edit profile (name and profile picture)
Change password (for password-authenticated users)
Logout functionality
Authentication method indicator
Modal and embedded view options

Usage

Embedded User Profile

function handleProfileEvents(appRes) {
  switch (appRes.app.event) {
    case "profile rendered":
      console.log("Profile rendered");
      break;
    case "profile update success":
      console.log("Profile updated", appRes.user?.data);
      break;
    case "password change success":
      console.log("Password changed");
      break;
    case "logout success":
      console.log("Logged out");
      break;
    default:
      console.log(appRes.app.event, appRes.app.message);
  }
}

renderHMUserProfile(
  "profile-container",
  {
    env: "dev",
    showLogout: true
  },
  handleProfileEvents
);

Modal User Profile

openHMUserProfileModal(
  {
    env: "dev"
  },
  handleProfileEvents
);

Removing or Closing User Profile

// To remove an embedded profile
removeHMUserProfile();

// To close a profile modal
closeHMUserProfileModal();

API Reference

renderHMUserProfile(containerId, options, callback)

Renders a user profile view for authenticated users. User data is automatically fetched using the widget's internal authentication token (which must be activated via activation code validation first).

Parameters:

containerId (string): DOM element id to render into.
options (Object, optional): Configuration options:
- env (string, optional): Environment ('dev', 'beta', 'prod'). Default: 'prod'.
- showLogout (boolean, optional): Whether to show the logout button. Default: true.
callback (Function): Callback function that receives event notifications.

removeHMUserProfile()

Removes the embedded profile view from the DOM (idempotent).

openHMUserProfileModal(options, callback)

Opens a modal rendering the user profile view. User data is automatically fetched using the widget's internal authentication token (which must be activated via activation code validation first).

Parameters: Same as renderHMUserProfile.

closeHMUserProfileModal()

Closes the profile modal if open (idempotent).

Events

The user profile feature emits the following events through the provided callback:

profile rendered: After successful DOM render.
profile modal opened: When the profile modal is opened.
profile modal closed: When the profile modal is closed programmatically.
profile modal closed by user: When the profile modal is closed by the user.
profile update success: When the profile is updated successfully. Includes updated user data.
profile update failed: When the profile update fails. Includes an error message.
password change success: When the password is changed successfully.
password change failed: When the password change fails. Includes an error message.
logout success: When the user is logged out successfully.
logout failed: When the logout fails. Includes an error message.

Security

The user profile feature follows security best practices:

Re-authentication is required for password changes
CSRF protection is implemented
Password strength requirements follow OWASP guidelines

Accessibility

The user profile feature is designed to be accessible:

Semantic HTML elements with appropriate ARIA attributes
Keyboard navigation
Focus management
Clear labels and error messages

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

hm-login-handler

This document contains detailed instructions on "How to Use" the package hm-login-handler.

1. Steps to install the package in your app:

2. Steps to use the package:

a. Steps to use the app as a form:

b. Steps to use the app as a modal:

3. Handling the app events response:

4. Understanding Activation Codes and Authentication Flow:

What is an Activation Code?

Authentication Flow:

Important Notes:

User Profile Feature

Features

Usage

Embedded User Profile

Modal User Profile

Removing or Closing User Profile

API Reference

renderHMUserProfile(containerId, options, callback)

removeHMUserProfile()

openHMUserProfileModal(options, callback)

closeHMUserProfileModal()

Events

Security

Accessibility