@devx-commerce/plugin-loyalty/README.md

A starter for Medusa plugins.

# Medusa Loyalty Plugin

A powerful loyalty points system plugin for Medusa e-commerce platform that allows you to manage customer loyalty points, track transactions, and implement reward programs.

## Features

- 💰 Credit and debit points for customers
- 📊 Track point transactions with detailed history
- ⏱️ Configurable point expiration
- 🔄 Multiple reference types (order, referral, manual)
- 📝 Customizable transaction descriptions
- 🎯 Easy integration with Medusa workflows

## Installation

1. Install the plugin in your Medusa backend:

```bash
npm install @devx-commerce/plugin-loyalty
# or
yarn add @devx-commerce/plugin-loyalty
```

2. Add the plugin to your `medusa-config.js`:

```js
const plugins = [
  // ... other plugins
  {
    resolve: "@devx-commerce/plugin-loyalty",
    options: {
      // Add your configuration options here
    },
  },
];
```

## Usage

### Managing Points

The plugin provides a simple interface to manage customer loyalty points:

```typescript
// Credit points to a customer
await loyaltyModuleService.addPoints({
  customerId: "cus_123",
  points: 100,
  referenceType: "order",
  description: "Points earned from order #123",
  expires_at: new Date("2024-12-31"), // Optional
});

// Deduct points from a customer
await loyaltyModuleService.deductPoints({
  customerId: "cus_123",
  points: 50,
  referenceType: "order",
  description: "Points redeemed for discount",
});

// Get customer's current points
const points = await loyaltyModuleService.getPoints("cus_123");

// Get transaction history
const transactions = await loyaltyModuleService.getTransactionHistory(
  "cus_123",
  {
    take: 10,
    skip: 0,
    type: "credit", // or "debit"
  }
);
```

### Workflow Integration

The plugin includes a workflow step for managing points:

```typescript
import { managePointsStep } from "@devx-commerce/plugin-loyalty/workflows";

// Use in your workflow
const result = await managePointsStep({
  customer_id: "cus_123",
  points: 100,
  type: "credit",
  reference_type: "order",
  description: "Points earned from order",
  expiry_days: 30, // Optional
});
```

## Configuration

The plugin can be configured through the `medusa-config.js` file:

```js
{
  resolve: "@devx-commerce/plugin-loyalty",
  options: {
    // Add your configuration options here
  },
}
```

## Requirements

- Node.js >= 20
- Medusa v2.4.0 or higher
- PostgreSQL database

## Development

1. Clone the repository:

```bash
git clone https://github.com/your-username/plugin-loyalty.git
```

2. Install dependencies:

```bash
yarn install
```

3. Build the plugin:

```bash
yarn build
```

4. Start development:

```bash
yarn dev
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

For support, please open an issue in the GitHub repository or contact the maintainers.

## About Medusa

This plugin is built for [Medusa](https://medusajs.com/), the open-source headless commerce engine.