npm package: @sialeadprom/merchanto-definitions
Description: Merchanto definitions lib
Author: Merchanto
Latest version: 2.7.7

# 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](https://gitlab.com/-/user_settings/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

```bash
# 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

```bash
yarn add @merchanto-chargeback/definitions
```

### 4. Usage

```typescript
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](https://www.conventionalcommits.org/):

| 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](https://gitlab.com/leadprom/merchanto/chargeback/merchanto-definitions/-/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](https://gitlab.com/leadprom/merchanto/chargeback/merchanto-definitions)
- [Package Registry](https://gitlab.com/leadprom/merchanto/chargeback/merchanto-definitions/-/packages)
- [CI/CD Pipelines](https://gitlab.com/leadprom/merchanto/chargeback/merchanto-definitions/-/pipelines)