Trace events activity with Treva — a minimal MongoDB-powered activity tracker.
npm install trevaTREVA is a robust Node.js package designed for storing and managing event logs in a MongoDB database with built-in authenticated data encryption. This package simplifies the process of logging events while ensuring the confidentiality and integrity of sensitive data.
---
- Secure Data Encryption: Utilizes AES-256-GCM authenticated encryption to protect sensitive event data at rest.
- Flexible Event Logging: Allows for adding and retrieving both encrypted and unencrypted events.
- Dynamic Collection Naming: Automatically creates dedicated collections for each eventType for efficient data organization.
- Environment-Based Configuration: Securely loads critical connection and encryption keys from environment variables.
---
To get started, install the TREVA package and its dependencies via npm.
``bash`
npm install treva
---
The package relies on two crucial environment variables for secure operation. You must set these before running your application.
- MONGO_URI: The full MongoDB connection string. For example: mongodb://localhost:27017/treva.
- ENCRYPTION_KEY: A strong, randomly generated 32-byte encryption key for AES-256-GCM. It is critical to keep this key a secret.
`bash`Example .env file content
MONGO_URI="mongodb://localhost:27017/treva"
ENCRYPTION_KEY="your-strong-random-key-here-of-32-bytes"
---
1. Connect to the Database
First, you must establish a connection to your MongoDB instance. Ensure you have added MONGO_URI in your .env.
`typescript
import { Database } from "treva";
async function initialize() {
try {
await Database.connect();
console.log("Database connection established.");
} catch (err) {
console.error("Failed to connect to database:", err);
}
}
initialize();
`
---
2. Add an Event
The addEvent method is used to securely log a new event into your database.
Method Signature:
`typescript`
EventLogger.addEvent({
eventType: string;
eventName: string;
data: object;
encryption?: boolean;
isOwn?: boolean;
});
Parameters:
- eventType: (Required) The type of event being logged (e.g., "user", "payment").
- eventName: (Required) The specific name of the event (e.g., "user_login", "credit_card_transaction").
- data: (Required) The event payload, which must be a JSON object.
- encryption: (Optional) A boolean flag to determine if the event's data should be encrypted before storage. Defaults to false.
- isOwn: (Optional) A boolean flag to control where the event is stored. Defaults to true.
Behavior:
- Collection Management: If isOwn is true, the event will be stored in a dedicated collection named . If isOwn is false, the event will be stored in the main master_event_logs collection.
- Data Encryption: If encryption is set to true, the data payload is encrypted using the provided ENCRYPTION_KEY before it is saved to the database. Otherwise, the data is stored as-is.
- Mandatory Fields: eventType, eventName, and data are all required parameters. If any of these are missing, the method will return an error.
---
3. Retrieve Events
The getEvents method allows you to retrieve event logs with flexible filtering and pagination.
`typescript`
EventLogger.getEvents({
eventType: string;
eventName: string;
filter?: object;
isEncrypted?: boolean;
page?: number;
limit?: number;
});
Parameters:
- eventType: (Required) The type of event to retrieve (e.g., "user", "payment").
- eventName: (Required) The specific name of the event (e.g., "user_login", "credit_card_transaction").
- filter: (Optional) An object to apply additional filters on the event's data field.
- isFromMaster: (Optional) A boolean flag that, when set to true, forces the query to run on the master_event_logs collection.
- isEncrypted: (Optional) A boolean flag to filter events by their encryption status. true fetches only encrypted data which will be automatically decrypted before being returned, while false fetches only unencrypted data.
- page: (Optional) The page number for pagination. Defaults to 1.
- limit: (Optional) The maximum number of events to return per page. Defaults to 10.
---
The security of your data depends entirely on the ENCRYPTION_KEY.
- Do not hardcode your key. Always use a secure environment variable.
- Protect the key. Store it securely and do not commit it to version control (e.g., using .gitignore`).
- Use a strong key. A randomly generated 32-byte string is recommended.
---
This project is licensed under the MIT License.