Brazilian PIX Key Extension for Directus

A comprehensive Directus extension bundle for handling Brazilian PIX keys with validation, formatting, and beautiful displays. This extension provides both an interface for data input and a display for presenting PIX keys throughout your Directus application.

🚀 Features

$3

The interface component provides a complete PIX key input experience with:

- Multi-type Support: Full support for all Brazilian PIX key types:
- CPF (Individual taxpayer ID) with official algorithm validation
- CNPJ (Company taxpayer ID) with official algorithm validation
- Phone numbers (landline and mobile) with area code validation
- Email addresses with standard format validation

- Smart Auto-detection: Automatically detects PIX key type based on input patterns
- CPF: 11 digits
- CNPJ: 14 digits
- Phone: 10-11 digits with area code recognition
- Email: Standard email format

- Real-time Validation:
- Validates CPF using official Brazilian algorithm (mod 11 check digits)
- Validates CNPJ using official Brazilian algorithm
- Validates phone numbers against all valid Brazilian area codes
- Validates email format with regex pattern
- Shows instant feedback with success/error indicators

- Intelligent Formatting:
- CPF: Formats as XXX.XXX.XXX-XX as you type
- CNPJ: Formats as XX.XXX.XXX/XXXX-XX as you type
- Phone: Formats as (XX) XXXXX-XXXX or (XX) XXXX-XXXX
- Email: Automatically lowercases and trims whitespace
- Restricts input to numbers only for CPF/CNPJ/Phone

- Type Selection Dropdown:
- Visual dropdown with icons for each PIX key type
- Manual type override capability
- Configurable allowed types restriction

- Input Features:
- Keyboard restrictions for numeric-only types
- Max length enforcement per type
- Copy/paste support with automatic formatting
- Blur event validation
- Visual feedback with icons and messages

$3

The display component provides rich visualization features:

- Type Identification:
- Automatic type detection from stored data
- Visual type icons (person for CPF, business for CNPJ, etc.)
- Support for both JSON and plain string storage formats

- Copy to Clipboard:
- One-click copying with visual feedback
- Animated success notification
- Fallback for older browsers
- Copies unformatted key value

- Privacy Features:
- Optional masking for sensitive data
- CPF: Masks as ..*-XX
- CNPJ: Masks as ../**-XX
- Configurable per display instance

- QR Code Support:
- QR code generation button (placeholder for future implementation)
- Modal dialog for QR code display
- Shows formatted PIX key value

- Responsive Design:
- Adapts to different screen sizes
- Mobile-optimized layout
- Flexible container widths

📦 Installation

$3

``bash
npm install directus-brazilian-pix
`

$3

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

🔧 Usage

$3

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 |
|--------|------|---------|-------------|
| Placeholder | String | Digite ou cole sua chave PIX | Custom placeholder text for the input field |
| Disabled | Boolean | false | Disable the input field |
| Required | Boolean | false | Make the field required with validation message |
| Auto-detect PIX Key Type | Boolean | true | Automatically detect PIX key type based on input format |
| Allowed PIX Key Types | Array | All types | Restrict which PIX key types are allowed (CPF, CNPJ, Phone, Email) |
| Default PIX Key Type | String | cpf | Default type when creating new items |
| Show Type Selector | Boolean | true | Show/hide the type selector dropdown |
| Validate Key Format | Boolean | true | Enable validation using official Brazilian algorithms |

$3

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 a badge/icon showing the PIX key type (CPF, CNPJ, Phone, Email) |
| Format Key | Boolean | true | Apply proper Brazilian formatting to CPF, CNPJ, and phone numbers |
| Hide Partial Key | Boolean | false | Mask part of the key for privacy (CPF and CNPJ only) |
| Enable Copy to Clipboard | Boolean | true | Allow users to copy the PIX key by clicking with visual feedback |
| Show QR Code Option | Boolean | false | Show a button to generate QR code for the PIX key |

📋 PIX Key Types

$3

| 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 |

$3

#### CPF Validation
- Uses the official Brazilian CPF algorithm (mod 11 check digits)
- Validates that all 11 digits aren't the same
- Calculates and verifies both check digits
- Automatically formats as XXX.XXX.XXX-XX

#### CNPJ Validation
- Uses the official Brazilian CNPJ algorithm
- Validates that all 14 digits aren't the same
- Calculates and verifies both check digits
- Automatically formats as XX.XXX.XXX/XXXX-XX

#### Phone Validation
- Validates against all 67 valid Brazilian area codes
- Supports both mobile (11 digits) and landline (10 digits) formats
- Mobile numbers must have 9 as the 3rd digit (after area code)
- Automatically formats as (XX) XXXXX-XXXX or (XX) XXXX-XXXX

#### Email Validation
- Standard email format validation using regex
- Automatically lowercases and trims whitespace
- Maximum length of 254 characters (RFC standard)

🎨 Styling & UI Features

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

$3

#### Icons by Type
- CPF: Person icon (person)
- CNPJ: Business icon (business)
- Phone: Phone icon (phone)
- Email: Email icon (email)
- Default: QR Code icon (qr_code)

#### Interactive Features
- Success Indicator: Green checkmark when validation passes
- Error Indicator: Red error icon with descriptive message
- Auto-detect Indicator: Shows when type is automatically detected
- Copy Animation: Smooth fade-in/out animation on successful copy
- Loading State: Hourglass icon during copy operation

#### Responsive Behavior
- Desktop: Side-by-side layout for type selector and input
- Mobile: Stacked vertical layout below 600px width
- Flexible Width: Components adapt to container width

📊 Data Storage

$3

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

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

$3

- Type Preservation: Maintains the PIX key type for proper validation
- Clean Values: Stores unformatted values (numbers only for CPF/CNPJ/Phone)
- Backward Compatibility: Display component can auto-detect type from plain strings
- Flexibility: Easily extendable for future PIX key types

$3

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

// CNPJ
{"key": "12345678000190", "type": "cnpj"}

// Phone
{"key": "11999999999", "type": "phone"}

// Email
{"key": "user@example.com", "type": "email"}
`

🔧 Development

$3

- Node.js 18+
- Directus 10+

$3

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

$3

`bash
npm run build
`

$3

`bash
npm run validate
`

🤝 Contributing

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

$3

- 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 file for details.

🐛 Issues & Support

Found a bug or need help? Please open an issue on GitHub.

🙏 Acknowledgments

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

🛠️ Technical Details

$3

The extension provides a comprehensive set of utility functions in pix-validators.ts:

#### Formatting Functions
- formatCPF(value: string): Formats CPF as XXX.XXX.XXX-XX
- formatCNPJ(value: string): Formats CNPJ as XX.XXX.XXX/XXXX-XX
- formatPhone(value: string): Formats phone as (XX) XXXXX-XXXX
- formatPixKey(value: string, type: PixKeyType): Universal formatter

#### Validation Functions
- isValidCPF(cpf: string): Validates CPF using official algorithm
- isValidCNPJ(cnpj: string): Validates CNPJ using official algorithm
- isValidPhone(phone: string): Validates phone with area code check
- isValidEmail(email: string): Validates email format
- validatePixKey(value: string, type: PixKeyType): Universal validator

#### Utility Functions
- detectPixKeyType(value: string): Auto-detects PIX key type
- cleanCPF/CNPJ/Phone(value: string): Removes formatting
- cleanPixKey(value: string, type: PixKeyType)`: Universal cleaner

$3

- Modern Browsers: Full support with Clipboard API
- Legacy Browsers: Fallback copy mechanism using textarea
- Mobile Support: Touch-optimized with responsive layouts
- Vue 3: Built with Vue 3 Composition API

$3

- Real-time Formatting: Efficient string manipulation without lag
- Debounced Validation: Validates on blur to avoid excessive checks
- Computed Properties: Reactive updates with Vue 3 reactivity
- Minimal Re-renders: Optimized component updates

📈 Roadmap

$3

- [ ] Real QR Code Generation: Generate actual PIX payment QR codes
- [ ] PIX API Integration: Validate keys against banking APIs
- [ ] Bulk Operations: Import/export multiple PIX keys
- [ ] EVP Support: Random PIX keys (UUID format)
- [ ] Webhooks: Trigger actions on PIX key changes
- [ ] Advanced Formatting: Custom formatting templates
- [ ] Multi-language Support: Internationalization
- [ ] Copy Format Options: Choose between formatted/unformatted copy
- [ ] PIX Key History: Track changes to PIX keys
- [ ] Integration Tests: Comprehensive test coverage