brtspd-audit

brtspd-audit is a simple and effective JavaScript package for auditing user interactions on your website. The package logs clicks on elements with a specific data-audit attribute, enabling easy tracking of user activity. It also supports handling elements that are dynamically loaded in modals or popovers.

Table of Contents

• Installation
• Usage
  • init
  • logAudit
  • loadEntries
• Options
  • InitOptions
  • LogAuditOptions
  • EntriesOptions
• License

Installation

To install brtspd-audit, you can use npm or yarn:

npm install brtspd-audit

or

yarn add brtspd-audit

Usage

The package exposes three primary functions: init, logAudit, and loadEntries. Each function provides different ways to handle audit logs based on your needs.

init

The init function automatically sets up event listeners for all elements with a data-audit attribute. It logs an audit entry when any of these elements are clicked.

init(options: InitOptions): void

InitOptions:

• url: The URL to which the audit data will be sent.

• user: The username of the person performing the action.

Example Usage

import { init } from 'brtspd-audit';

const options = {
  url: 'https://example.com/audit-log',
  user: 'john_doe'
};

init(options);

This function will attach click event listeners to all elements with the data-audit attribute. When clicked, it sends an audit log with the data available on the element (such as data-audit, data-audit-message, data-page), as well as the username provided in the InitOptions.

logAudit

The logAudit function allows you to manually log an audit entry. This is useful for cases where the element is inside a modal or popover, where the data-audit element may not be available in the DOM initially.

logAudit(options: LogAuditOptions): void

LogAuditOptions:

• url: The URL to which the audit data will be sent.

• meta: An object containing metadata for the audit log:

  • actionType: The type of action performed (e.g., "click").

  • message: A custom message describing the action.

  • user: The username of the person performing the action.

  • page: The name or URL of the page where the action occurred.

Example Usage

import { logAudit } from 'brtspd-audit';

const options = {
  url: 'https://example.com',
  meta: {
    actionType: 'click',
    message: 'Clicked button in modal',
    user: 'john_doe',
    page: 'modal-page'
  }
};

logAudit(options);

This function manually logs an audit entry with the provided metadata, regardless of whether the element was dynamically added to the page (e.g., inside a modal or popover).

loadEntries

The loadEntries function retrieves all the audit entries created so far from a specified URL.

loadEntries(options: EntriesOptions): AuditLogEntry[]

EntriesOptions

• url: The URL from which to fetch the audit log entries.

Example Usage

import { loadEntries } from 'brtspd-audit';

const options = {
  url: 'https://example.com'
};

const logs = loadEntries(options);

console.log(logs); // An array of audit log entries

This function fetches the audit entries from the provided URL and returns them as JSON data.

Options

InitOptions

This object is used with the init function.

type InitOptions = {
  url: string;  // The URL where the audit logs will be sent
  user: string; // The user performing the actions
};

LogAuditOptions

This object is used with the logAudit function.

type LogAuditOptions = {
  url: string;  // The URL where the audit logs will be sent
  meta: {
    actionType: string; // Type of action (e.g., 'click', 'view')
    message: string;    // Custom message describing the action
    user: string;       // Username of the person performing the action
    page: string;       // Name or URL of the page where the action took place
  };
};

EntriesOptions

This object is used with the loadEntries function.

type EntriesOptions = {
  url: string; // The URL for which to load audit log entries
};

License

brtspd-audit is licensed under the MIT License.