Merchanto Definitions Library

A TypeScript library containing shared enums, interfaces, and type definitions for Merchanto chargeback services.

📦 Installation

Prerequisites

You need to authenticate with GitLab Package Registry to install this private package.

1. Create GitLab Access Token

1. Go to GitLab Personal Access Tokens
2. Create a token with the following scopes:
   • read_api - to read packages
   • read_repository - if you need to clone repos
3. Copy your token (you won't see it again!)

2. Configure Registry

# Set token via environment variable
export MERCHANTO_CB_NPM_REGISTRY_TOKEN=YOUR_GITLAB_TOKEN

# Create .npmrc with placeholder
echo "@merchanto-chargeback:registry=https://gitlab.com/api/v4/groups/107572970/-/packages/npm/" > .npmrc
echo "//gitlab.com/api/v4/groups/107572970/-/packages/npm/:_authToken=\${MERCHANTO_CB_NPM_REGISTRY_TOKEN}" >> .npmrc
echo "//gitlab.com/api/v4/projects/70450325/packages/npm/:_authToken=\${MERCHANTO_CB_NPM_REGISTRY_TOKEN}" >> .npmrc
echo "//gitlab.com/api/v4/projects/70438423/packages/npm/:_authToken=\${MERCHANTO_CB_NPM_REGISTRY_TOKEN}" >> .npmrc
echo "//gitlab.com/api/v4/projects/70450277/packages/npm/:_authToken=\${MERCHANTO_CB_NPM_REGISTRY_TOKEN}" >> .npmrc

3. Install Package

yarn add @merchanto-chargeback/definitions

4. Usage

import { 
  ChargebackEventStatusEnum,
  PaymentProviderEnum,
  CurrencyEnum 
} from '@merchanto-chargeback/definitions';

// Use enums in your code
const status = ChargebackEventStatusEnum.PENDING;
const provider = PaymentProviderEnum.STRIPE;
const currency = CurrencyEnum.USD;

⚠️ Important Notes

• Version 3.0.0+ is available only on GitLab Package Registry
• Legacy versions (≤2.6.1) remain on npm registry
• Breaking changes may exist between old npm package and new GitLab package
• Package scope changed from @sialeadprom to @merchanto-chargeback

🚀 Publishing New Versions (For Maintainers)

Automated Versioning with Semantic Release

Versions are automatically determined by commit messages using Conventional Commits:

| Commit Message Format | Release Type | Example | |-----------------------|--------------|---------| | fix: description | Patch (3.0.0 → 3.0.1) | fix: resolve enum import error | | feat: description | Minor (3.0.0 → 3.1.0) | feat: add new payment provider enum | | feat!: description or BREAKING CHANGE: | Major (3.0.0 → 4.0.0) | feat!: rename ChargebackStatus enum |

Publishing Steps

1. Make your changes and commit with conventional commit messages
2. Push to main branch
3. Go to GitLab CI/CD → Pipelines
4. Manually trigger the publish job (for security, publishing requires manual approval)
5. Semantic-release will:
   • Analyze commits since last release
   • Determine appropriate version bump
   • Build TypeScript definitions
   • Publish to GitLab Package Registry
   • Create GitLab release with changelog

Environment Setup for Publishing

The pipeline requires the GITLAB_NPM_REPO_TOKEN environment variable with a GitLab token that has:

• api scope (for publishing packages)
• write_repository scope (for creating releases)

📚 Available Exports

This package exports enums and interfaces for:

• Payment Processing: PaymentProviderEnum, PaymentEventStatusEnum, CurrencyEnum
• Chargeback Management: ChargebackEventStatusEnum, ChargebackPreventionSourceEnum
• User Management: UserRolesEnum, UserStatusEnum, UserServicesEnum
• Website Configuration: WebsiteStatusEnum
• Billing: BillingStatusEnum
• Card Processing: CardTypeEnum, StripeChargeRefundStatusEnum

🔗 Related Links

• GitLab Project
• Package Registry
• CI/CD Pipelines