# Merchant

An Elixir client for the [Revolut Merchant API](https://developer.revolut.com/docs/merchant/merchant-api) (v2024-09-01). This library provides a type-safe and ergonomic interface for integrating with Revolut's payment processing services.

## Features

- **Complete API Coverage**: Supports all major Revolut Merchant API endpoints
- **Type Safety**: Full Elixir type specifications for all data structures
- **Structured Responses**: Automatic conversion of JSON responses to Elixir structs
- **Error Handling**: Comprehensive error handling with proper error types
- **Configuration**: Easy configuration for different environments (sandbox/production)

## Installation

Add `merchant` to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:merchant, "~> 0.1.0"}
  ]
end
```

Then run:
```bash
mix deps.get
```

## Configuration

### API Keys

You'll need to configure your Revolut Merchant API credentials. Add the following to your configuration:

```elixir
# config/config.exs
config :merchant,
  api_key: System.get_env("REVOLUT_MERCHANT_API_KEY"),
  base_url: System.get_env("REVOLUT_MERCHANT_BASE_URL", "https://sandbox-merchant.revolut.com")
```

### Environment Variables

Set your API credentials as environment variables:

```bash
# For sandbox testing
export REVOLUT_MERCHANT_API_KEY="your_sandbox_secret_key"
export REVOLUT_MERCHANT_BASE_URL="https://sandbox-merchant.revolut.com"

# For production
export REVOLUT_MERCHANT_API_KEY="your_production_secret_key"
export REVOLUT_MERCHANT_BASE_URL="https://merchant.revolut.com"
```

## Usage

### Orders

Create, retrieve, update, and manage orders:

```elixir
alias Merchant.Orders

# Create a new order
{:ok, order} = Orders.create(%{
  amount: 1000,  # Amount in minor units (e.g., cents)
  currency: "USD",
  description: "Test order",
  capture_mode: "AUTOMATIC"
})

# Retrieve an order
{:ok, order} = Orders.retrieve("order_id")

# Update an order
{:ok, updated_order} = Orders.update("order_id", %{
  description: "Updated description"
})

## API Versioning

This client supports the Revolut Merchant API version `2024-09-01`. The API version is automatically included in requests where required.

## Error Handling

All functions return either `{:ok, result}` or `{:error, error}` tuples except the bang functions:

```elixir
case Orders.create(order_params) do
  {:ok, order} ->
    # Handle successful order creation
    IO.puts("Order created: #{order.id}")
    
  {:error, error} ->
    # Handle error
    IO.puts("Error creating order: #{inspect(error)}")
end
```

## Data Structures

The library provides comprehensive type definitions for all API data structures:

- `Merchant.OrderV4` - Order objects
- `Merchant.Customer` - Customer objects  
- `Merchant.PaymentV2` - Payment objects
- `Merchant.LineItem` - Line item objects
- `Merchant.Shipping` - Shipping information
- `Merchant.Metadata` - Metadata objects
- And more...

## Development

### Running Tests

```bash
mix test
```

### Code Quality

```bash
# Run all consistency checks
mix consistency

# Format code
mix format

# Run Credo for code analysis
mix credo

# Run Dialyzer for type checking
mix dialyzer
```

## API Documentation

For detailed information about the Revolut Merchant API, visit:
- [Revolut Merchant API Documentation](https://developer.revolut.com/docs/merchant/merchant-api)
- [API Reference](https://developer.revolut.com/docs/merchant/merchant-api)

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Support

For issues related to this Elixir client, please open an issue on GitHub.

For Revolut Merchant API support, visit the [Revolut Developer Portal](https://developer.revolut.com/).