@pillexa/medusa-subscription-plugin/README.md

A subscription management plugin for Medusa e-commerce

# @pillexa/medusa-subscription-plugin

A comprehensive subscription management plugin for Medusa e-commerce platform, built with TypeScript.

## Features

- 🚀 **Subscription Management**: Create, update, and cancel subscriptions
- 🔄 **Recurring Billing**: Support for weekly, monthly, and yearly billing cycles
- 📡 **Event-Driven**: Automatic subscription creation from orders
- 🛡️ **TypeScript**: Full TypeScript support with type safety
- 🧪 **Testing**: Comprehensive test coverage
- 📚 **RESTful API**: Complete API endpoints for subscription management
- 🔔 **Event Handling**: Subscribe to subscription lifecycle events

## Installation

```bash
npm install @pillexa/medusa-subscription-plugin
```

## Configuration

Add the plugin to your Medusa configuration:

```typescript
// medusa-config.js
const plugins = [
  // ... other plugins
  {
    resolve: "@pillexa/medusa-subscription-plugin",
    options: {
      // Plugin options can be added here
    }
  }
];

module.exports = {
  projectConfig: {
    // ... your project config
  },
  plugins
};
```

## Usage

### Service Usage

```typescript
import { SubscriptionService } from "@pillexa/medusa-subscription-plugin";

// Create a subscription
const subscription = await subscriptionService.create({
  customer_id: "cust_123",
  product_id: "prod_456",
  interval: "monthly",
  status: "active"
});

// Retrieve a subscription
const subscription = await subscriptionService.retrieve("sub_123");

// List subscriptions
const subscriptions = await subscriptionService.list({
  customer_id: "cust_123",
  status: "active"
});

// Update a subscription
const updatedSubscription = await subscriptionService.update("sub_123", {
  status: "paused",
  interval: "yearly"
});

// Cancel a subscription
const cancelledSubscription = await subscriptionService.cancel("sub_123");

// Process billing
const billingResult = await subscriptionService.processBilling("sub_123");
```

### API Endpoints

The plugin provides the following REST API endpoints:

#### GET /subscriptions
List all subscriptions with optional filters.

**Query Parameters:**
- `customer_id` (string): Filter by customer ID
- `status` (string): Filter by status (active, cancelled, paused, expired)
- `interval` (string): Filter by interval (weekly, monthly, yearly)

**Example:**
```bash
GET /subscriptions?customer_id=cust_123&status=active
```

#### GET /subscriptions/:id
Get a specific subscription by ID.

**Example:**
```bash
GET /subscriptions/sub_123
```

#### POST /subscriptions
Create a new subscription.

**Request Body:**
```json
{
  "customer_id": "cust_123",
  "product_id": "prod_456",
  "interval": "monthly",
  "status": "active"
}
```

#### PUT /subscriptions/:id
Update a subscription.

**Request Body:**
```json
{
  "status": "paused",
  "interval": "yearly"
}
```

#### DELETE /subscriptions/:id
Cancel a subscription.

#### POST /subscriptions/:id/billing
Process billing for a subscription.

#### GET /subscriptions/customer/:customer_id
Get all subscriptions for a specific customer.

#### GET /subscriptions/status/:status
Get all subscriptions with a specific status.

### Event Handling

The plugin automatically handles the following events:

#### Order Events
- `order.placed`: Creates subscriptions for subscription products
- `order.payment_captured`: Handles payment processing
- `order.cancelled`: Handles order cancellation

#### Subscription Events
- `subscription.created`: Triggered when a subscription is created
- `subscription.updated`: Triggered when a subscription is updated
- `subscription.cancelled`: Triggered when a subscription is cancelled
- `subscription.billing_processed`: Triggered when billing is processed

### Types

```typescript
interface Subscription {
  id: string;
  customer_id: string;
  product_id: string;
  interval: 'weekly' | 'monthly' | 'yearly';
  status: 'active' | 'cancelled' | 'paused' | 'expired';
  created_at: Date;
  updated_at: Date;
  next_billing_date: Date;
  order_id?: string;
}

interface CreateSubscriptionData {
  customer_id: string;
  product_id: string;
  interval: SubscriptionInterval;
  status?: SubscriptionStatus;
  order_id?: string;
}

interface UpdateSubscriptionData {
  customer_id?: string;
  product_id?: string;
  interval?: SubscriptionInterval;
  status?: SubscriptionStatus;
  next_billing_date?: Date;
}
```

## Development

### Prerequisites

- Node.js 18+
- npm or yarn
- Medusa backend

### Setup

1. Clone the repository
2. Install dependencies:
   ```bash
   cd packages/subscriptions
   npm install
   ```

3. Build the plugin:
   ```bash
   npm run build
   ```

4. Run tests:
   ```bash
   npm test
   ```

5. Run linting:
   ```bash
   npm run lint
   ```

### Scripts

- `npm run build`: Build the TypeScript code
- `npm run watch`: Watch for changes and rebuild
- `npm test`: Run tests
- `npm run test:watch`: Run tests in watch mode
- `npm run lint`: Run ESLint
- `npm run lint:fix`: Fix ESLint issues
- `npm run type-check`: Run TypeScript type checking

## Testing

The plugin includes comprehensive tests covering:

- Service methods (create, retrieve, list, update, cancel, processBilling)
- API endpoints
- Event handling
- Error cases
- Type validation

Run tests with:
```bash
npm test
```

Run tests with coverage:
```bash
npm test -- --coverage
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

## License

MIT

## Support

For support, please open an issue on GitHub or contact the Pillexa team.

## Changelog

### v0.1.0
- Initial release
- Basic subscription management
- TypeScript support
- RESTful API endpoints
- Event-driven architecture
- Comprehensive testing