Contributing to MindPaystack

# 1. Fork and clone the repository
git clone https://github.com/Dartmind-OpenSource/mind-paystack.git
cd mind-paystack
 
# 2. Install Melos globally (if not already installed)
dart pub global activate melos
 
# 3. Bootstrap the project
melos bootstrap
 
# 4. Verify setup
melos run test
melos run analyze

mind-paystack/
├── packages/
│   └── mind_paystack/          # Core SDK package
├── apps/
│   ├── ex00_checkout_basic/    # Dart CLI example
│   └── ex01_checkout_flutter/  # Flutter app example  
├── docs/                       # Documentation site
├── melos.yaml                  # Monorepo configuration
└── README.md                   # Project overview

git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-description

# Run all tests across the monorepo
melos run test
 
# Run tests for specific package
melos run test --scope=mind_paystack
 
# Analyze code
melos run analyze
 
# Format code
melos run format

git add .
git commit -m "feat: add your feature description"
git push origin feature/your-feature-name

// Classes: PascalCase
class PaystackTransaction {}
 
// Functions and variables: camelCase
void initializePayment() {}
final String transactionReference = 'txn_123';
 
// Constants: lowerCamelCase with const
const String defaultCurrency = 'NGN';
const int maxRetryAttempts = 3;
 
// Private members: leading underscore
String _buildAuthHeader() {}

/// Initializes a payment transaction with Paystack.
///
/// This method creates a new transaction and returns the authorization URL
/// that customers can use to complete their payment. The transaction will
/// be created with the specified [amount] and [email].
///
/// Example:
/// ```dart
/// final transaction = await PaystackAPI.initializeTransaction(
///   amount: 50000, // ₦500.00 in kobo
///   email: 'customer@example.com',
/// );
/// print('Payment URL: ${transaction.authorizationUrl}');
/// ```
///
/// [amount] The payment amount in kobo (required, must be positive)
/// [email] The customer's email address (required, must be valid)
/// [currency] The payment currency (optional, defaults to 'NGN')
/// [reference] Custom transaction reference (optional, auto-generated if null)
/// [metadata] Additional transaction metadata (optional)
/// 
/// Returns a [PaystackTransaction] containing the authorization URL and details.
/// 
/// Throws [PaystackException] if the API request fails.
/// Throws [ValidationException] if the input parameters are invalid.
Future<PaystackTransaction> initializeTransaction({
  required int amount,
  required String email,
  String currency = 'NGN',
  String? reference,
  Map<String, dynamic>? metadata,
}) async {
  // Implementation
}

try {
  final result = await paystackApi.call();
  return result;
} on PaystackException catch (e) {
  // Handle Paystack-specific errors
  _logger.error('Paystack API error: ${e.message}', e);
  rethrow;
} on HttpException catch (e) {
  // Handle network errors
  _logger.error('Network error: ${e.message}', e);
  throw PaystackException('Network request failed: ${e.message}');
} catch (e) {
  // Handle unexpected errors
  _logger.error('Unexpected error: $e', e);
  throw PaystackException('An unexpected error occurred');
}

class PaymentButton extends StatefulWidget {
  /// Creates a payment button widget.
  const PaymentButton({
    super.key,
    required this.amount,
    required this.onPaymentSuccess,
    this.onPaymentError,
    this.currency = 'NGN',
  });
 
  final int amount;
  final VoidCallback onPaymentSuccess;
  final void Function(String error)? onPaymentError;
  final String currency;
 
  @override
  State<PaymentButton> createState() => _PaymentButtonState();
}

void main() {
  group('PaystackAPI', () {
    late PaystackAPI api;
    late MockHttpClient mockClient;
    
    setUp(() {
      mockClient = MockHttpClient();
      api = PaystackAPI(httpClient: mockClient);
    });
    
    group('initializeTransaction', () {
      test('should return transaction when API call succeeds', () async {
        // Arrange
        when(() => mockClient.post(any(), body: any(named: 'body')))
            .thenAnswer((_) async => Response(
                  '{"status": true, "data": {"authorization_url": "https://checkout.paystack.com/xyz"}}',
                  200,
                ));
        
        // Act
        final result = await api.initializeTransaction(
          amount: 50000,
          email: 'test@example.com',
        );
        
        // Assert
        expect(result.authorizationUrl, equals('https://checkout.paystack.com/xyz'));
        verify(() => mockClient.post(
              Uri.parse('https://api.paystack.co/transaction/initialize'),
              body: any(named: 'body'),
            )).called(1);
      });
      
      test('should throw PaystackException when API returns error', () async {
        // Arrange
        when(() => mockClient.post(any(), body: any(named: 'body')))
            .thenAnswer((_) async => Response(
                  '{"status": false, "message": "Invalid email"}',
                  400,
                ));
        
        // Act & Assert
        expect(
          () => api.initializeTransaction(
            amount: 50000,
            email: 'invalid-email',
          ),
          throwsA(isA<PaystackException>()
              .having((e) => e.message, 'message', contains('Invalid email'))),
        );
      });
      
      group('input validation', () {
        test('should throw ValidationException for negative amount', () {
          expect(
            () => api.initializeTransaction(
              amount: -100,
              email: 'test@example.com',
            ),
            throwsA(isA<ValidationException>()),
          );
        });
        
        test('should throw ValidationException for invalid email', () {
          expect(
            () => api.initializeTransaction(
              amount: 50000,
              email: 'not-an-email',
            ),
            throwsA(isA<ValidationException>()),
          );
        });
      });
    });
  });
}

# Run all tests in the monorepo
melos run test
 
# Run tests with coverage
melos run test:coverage
 
# Run tests for specific package
melos run test --scope=mind_paystack
 
# Run specific test file
cd packages/mind_paystack
dart test test/api/paystack_api_test.dart
 
# Run tests with specific name pattern
dart test --name "initializeTransaction"

## Summary
Brief description of the changes and their purpose.
 
## Type of Change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that causes existing functionality to not work as expected)
- [ ] Documentation update
- [ ] Refactoring (no functional changes)
- [ ] Test improvements
 
## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests added/updated
- [ ] Manual testing performed
- [ ] Example applications tested
 
## Documentation
- [ ] Code comments added/updated
- [ ] API documentation updated
- [ ] README updated (if applicable)
- [ ] CHANGELOG.md updated
 
## Screenshots (if applicable)
<!-- Add screenshots for UI changes -->
 
## Related Issues
<!-- Link to related issues -->
Closes #123
References #456
 
## Additional Notes
<!-- Any additional information for reviewers -->

# 1. Update version numbers
melos version
 
# 2. Update CHANGELOG.md
# Add entry for new version
 
# 3. Create release commit
git add .
git commit -m "chore: release v1.2.0"
 
# 4. Create and push tag
git tag v1.2.0
git push origin main --tags
 
# 5. Publish to pub.dev (maintainers only)
melos publish

// ❌ Never hardcode API keys
const String secretKey = 'sk_test_your_key_here';
 
// ✅ Always use environment variables or secure storage
final String secretKey = Platform.environment['PAYSTACK_SECRET_KEY'] ?? 
    throw Exception('PAYSTACK_SECRET_KEY not found');

// Always validate user inputs
void validateEmail(String email) {
  if (!RegExp(r'^[^@]+@[^@]+\.[^@]+$').hasMatch(email)) {
    throw ValidationException('Invalid email format');
  }
}
 
void validateAmount(int amount) {
  if (amount <= 0) {
    throw ValidationException('Amount must be positive');
  }
  if (amount > 100000000) { // 1 million naira in kobo
    throw ValidationException('Amount exceeds maximum limit');
  }
}

// ❌ Don't expose sensitive information in errors
throw Exception('Database connection failed: password=secret123');
 
// ✅ Provide helpful but secure error messages
throw PaystackException('Unable to process payment. Please try again.');

/// Example of good code documentation:
/// 
/// ```dart
/// // Initialize the SDK
/// await MindPaystack.initialize(PaystackConfig(
///   publicKey: 'pk_test_your_key',
///   secretKey: 'sk_test_your_key',
///   environment: Environment.test,
/// ));
/// 
/// // Create a transaction
/// final transaction = await MindPaystack.instance.transaction.initialize(
///   InitializeTransactionOptions(
///     amount: '50000', // ₦500.00 in kobo
///     email: 'customer@example.com',
///   ),
/// );
/// 
/// print('Payment URL: ${transaction.data?.authorizationUrl}');
/// ```

{
  "dart.flutterSdkPath": "/path/to/flutter",
  "dart.lineLength": 80,
  "editor.rulers": [80],
  "editor.formatOnSave": true,
  "dart.runPubGetOnPubspecChanges": true,
  "files.associations": {
    "melos.yaml": "yaml"
  }
}

# Bootstrap all packages
melos bootstrap
 
# Run tests across all packages
melos run test
 
# Run analysis across all packages
melos run analyze
 
# Format code across all packages
melos run format
 
# Clean all packages
melos clean
 
# List all packages
melos list
 
# Run command in specific package
melos exec --scope=mind_paystack -- dart test

#!/bin/bash
echo "Running pre-commit checks..."
 
# Format code
echo "Formatting code..."
melos run format
 
# Analyze code
echo "Analyzing code..."
melos run analyze --no-fatal-infos
 
# Run tests
echo "Running tests..."
melos run test
 
echo "Pre-commit checks passed!"

chmod +x .git/hooks/pre-commit

# Clear pub cache and retry
dart pub cache clean
melos clean
melos bootstrap

// ❌ Don't make unnecessary API calls
for (final transaction in transactions) {
  await api.verifyTransaction(transaction.reference);
}
 
// ✅ Batch operations when possible
final verifications = await Future.wait(
  transactions.map((t) => api.verifyTransaction(t.reference)),
);

// ✅ Dispose of streams and subscriptions
class PaymentService {
  StreamSubscription? _subscription;
  
  void dispose() {
    _subscription?.cancel();
  }
}

// ✅ Implement retry logic for transient failures
Future<T> withRetry<T>(Future<T> Function() operation, {
  int maxAttempts = 3,
  Duration delay = const Duration(seconds: 1),
}) async {
  for (int attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await operation();
    } catch (e) {
      if (attempt == maxAttempts || !_isRetryableError(e)) rethrow;
      await Future.delayed(delay * attempt);
    }
  }
  throw StateError('This should never be reached');
}