directus-brazilian-pix/README.md

Brazilian PIX key extensions for Directus - Complete PIX key input with type selection and validation (CPF, CNPJ, Phone, Email)

# Brazilian PIX Key Extension for Directus

A comprehensive Directus extension bundle for handling Brazilian PIX keys with validation, formatting, and beautiful displays.

## 🚀 Features

### PIX Key Interface
- **Multi-type Support**: CPF, CNPJ, Phone numbers, and Email addresses
- **Auto-detection**: Automatically detects PIX key type based on input format
- **Real-time Validation**: Validates keys using official Brazilian algorithms
- **Smart Formatting**: Applies proper formatting as you type
- **Type Selection**: Dropdown to manually select PIX key type
- **Configurable**: Extensive configuration options for different use cases

### PIX Key Display
- **Type Badges**: Visual indicators showing the PIX key type
- **Copy to Clipboard**: One-click copying with visual feedback
- **Privacy Mode**: Option to mask sensitive information (CPF/CNPJ)
- **QR Code Generation**: Generate QR codes for PIX keys (placeholder)
- **Responsive Design**: Works on all screen sizes

## 📦 Installation

### From NPM (Recommended)
```bash
npm install directus-brazilian-pix
```

### Manual Installation
1. Download the latest release
2. Extract to your Directus extensions folder
3. Restart your Directus instance

## 🔧 Usage

### Interface Configuration

Add the Brazilian PIX Key interface to any string field:

1. Go to Settings > Data Model
2. Select your collection and field
3. Choose "Brazilian PIX Key" as the interface
4. Configure the options as needed

#### Interface Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| **Auto-detect Type** | Boolean | `true` | Automatically detect PIX key type based on input |
| **Allowed Types** | Array | All types | Restrict which PIX key types are allowed |
| **Default Type** | String | `cpf` | Default type when creating new items |
| **Validate Key** | Boolean | `true` | Enable validation using official algorithms |
| **Required** | Boolean | `false` | Make the field required |

### Display Configuration

Configure the display to show PIX keys with type badges:

1. Go to your collection layout
2. Select the PIX key field
3. Choose "Brazilian PIX Key Display" as the display
4. Configure the display options

#### Display Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| **Show Type Badge** | Boolean | `true` | Display type badge (CPF, CNPJ, etc.) |
| **Format Key** | Boolean | `true` | Apply formatting to displayed keys |
| **Hide Partial Key** | Boolean | `false` | Mask part of the key for privacy |
| **Copy to Clipboard** | Boolean | `true` | Enable copy functionality |
| **Show QR Code** | Boolean | `false` | Show QR code generation button |

## 📋 PIX Key Types

### Supported Types

| Type | Description | Format | Example |
|------|-------------|--------|---------|
| **CPF** | Individual taxpayer ID | XXX.XXX.XXX-XX | 123.456.789-01 |
| **CNPJ** | Company taxpayer ID | XX.XXX.XXX/XXXX-XX | 12.345.678/0001-90 |
| **Phone** | Mobile/landline number | (XX) XXXXX-XXXX | (11) 99999-9999 |
| **Email** | Email address | user@domain.com | usuario@email.com |

### Validation Rules

- **CPF**: Validates using the official Brazilian CPF algorithm
- **CNPJ**: Validates using the official Brazilian CNPJ algorithm  
- **Phone**: Validates area codes and mobile number formats
- **Email**: Standard email format validation

## 🎨 Styling

The extension uses Directus design tokens and follows the system theme automatically.

### Type Badge Colors
- **CPF**: Blue (`--blue`)
- **CNPJ**: Purple (`--purple`) 
- **Phone**: Green (`--green`)
- **Email**: Orange (`--orange`)

## 📊 Data Storage

PIX keys are stored as JSON strings containing both the key and its type:

```json
{
  "key": "12345678901",
  "type": "cpf"
}
```

This allows for:
- Proper validation based on type
- Correct formatting in displays
- Type-aware functionality

## 🔧 Development

### Prerequisites
- Node.js 18+
- Directus 10+

### Local Development
```bash
# Clone the repository
git clone https://github.com/brunribeiro/directus-brazilian-pix.git

# Install dependencies
cd directus-brazilian-pix
npm install

# Build the extension
npm run build

# Link for development
npm run link
```

### Building
```bash
npm run build
```

### Validation
```bash
npm run validate
```

## 🤝 Contributing

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

### Development Guidelines
- Follow the existing code style
- Add tests for new features
- Update documentation
- Ensure all validations pass

## 📝 License

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

## 🐛 Issues & Support

Found a bug or need help? Please [open an issue](https://github.com/brunribeiro/directus-brazilian-pix/issues) on GitHub.

## 🙏 Acknowledgments

- Brazilian Central Bank for PIX key specifications
- Directus team for the amazing extension SDK
- The Brazilian development community

## 📈 Roadmap

- [ ] Real QR Code generation
- [ ] PIX key validation API integration
- [ ] Bulk PIX key operations
- [ ] Additional PIX key types (EVP - Random keys)
- [ ] Export/import functionality