ampersand-common-module

📦 Overview

ampersand-common-module contains the shared backend modules used across the HubbleOrion ERP ecosystem.
It centralizes commonly used functionality to ensure standardization, reduce duplication, and improve maintainability across microservices.

📚 Included Modules

🔐 Auth

Provides Redis-based authentication helpers and a slug middleware for securing API routes.

📝 Audit Log

Captures critical user actions and trackable events performed within the ERP.

⚙️ Constants

Central repository of constants used across services, ensuring consistency.

📁 File Upload

End-to-end module for uploading, retrieving, and managing files from Cloud Storage or Local Storage.

📄 Swagger Helpers

Wrapper utilities over Swagger decorators to simplify repetitive API documentation code.

📨 Kafka Helpers

Utility abstractions for Kafka producers and consumers, enabling consistent message flows across microservices.

📊 Excel Import/Export

Utility toolkit for importing and exporting data in Excel/CSV formats.

🧰 Utils

A set of globally reusable utility functions.

🚀 Publishing Guide

This package uses Bitbucket Pipelines for automated publishing to npm.

1. Version Bump

Before merging your changes to main, update the version in package.json. You can use the following command:

npm version patch   # For bug fixes (1.0.x)
npm version minor   # For new features (1.x.0)
npm version major   # For breaking changes (x.0.0)

Note: This command also updates package.json and creates a git tag.

2. Push & Merge

Push your changes to a feature branch and create a Pull Request. Once approved, merge it into the main branch.

3. Automated Publish

The Bitbucket Pipeline will automatically:

1. Install dependencies (npm ci).
2. Build the project (npm run build).
3. Publish to npm (npm publish).

[!IMPORTANT] Ensure the NPM_TOKEN is configured in Bitbucket Repository Variables (Settings > Repository variables) for the pipeline to succeed.

Alternative: Manual Publish

If you need to publish manually, ensure you have the correct permissions and follow these steps:

1. Build:

   npm run build

2. Login (if not already):

   npm login

3. Publish:

   npm publish --access public

🛠️ Local Development

Build

To compile TypeScript locally for testing:

npm run build

Git Integration

The dist/ directory is ignored by git to keep the repository clean. Build artifacts are only generated during the CI/CD process or for local testing.