raisedonors

The RaiseDonors module provides integration between Drupal 11 and the RaiseDonors fundraising platform using the RaiseDonors 2.0 API. Currently, this module allows for the automatic creation and updating of Drupal user accounts when donors are created or updated in RaiseDonors. However, more features and functionality will be added later.

## Requirements

• Drupal 11
• PHP 8.3 or PHP 8.4
• Key module
• Address module
• A RaiseDonors 2.0 account

## Installation

1. Download and install the module using Composer:
```
composer require drupal/raisedonors
```

2. Enable the module:
```
drush en raisedonors
```

3. Configure the module at `/admin/config/raisedonors`

## Configuration

1. Navigate to `/admin/config/raisedonors` in your Drupal site.
2. Select "Test" mode while setting up the integration.
3. Create a key in the [Key module](https://www.drupal.org/project/key) to store your RaiseDonors API token.
4. Select the key from the dropdown in the RaiseDonors configuration form.
5. Click "Test API Connection" to verify that your configuration is correct.
6. Configure a webhook security token to secure webhook endpoints.
7. Configure synchronization settings:
8. Set automatic sync frequency (never, daily, weekly, or monthly)
9. Use the "Sync Donors Now" button for immediate full synchronization
10. Once you've confirmed the connection is working, switch to "Live" mode to activate the integration.

## Features

• One-way synchronization of donor data from RaiseDonors to Drupal
• Automatic creation of Drupal user accounts when donors are created in RaiseDonors
• Automatic updating of Drupal user accounts when donors are updated in RaiseDonors
• Configurable test mode for safe integration setup
• Donor management view at `/admin/donors`
• Webhook security token validation for enhanced security
• Scheduled donor synchronization via cron
• Manual sync button with progress indicator
• Detailed sync statistics and logging

## Synchronization Options

### Manual Synchronization

The module provides a "Sync Donors Now" button on the settings page that initiates a full donor synchronization from RaiseDonors. This process:

1. Connects to the RaiseDonors API
2. Retrieves all donors in batches
3. Creates or updates Drupal users for each donor
4. Displays a progress bar during the sync process
5. Shows a detailed summary of results upon completion

### Scheduled Synchronization

You can configure the module to automatically sync donors on a regular schedule:

• Daily: Sync runs once every 24 hours
• Weekly: Sync runs once every 7 days
• Monthly: Sync runs once every 30 days
• Never: No automatic sync (manual only)

Scheduled syncs run during Drupal's cron process, so make sure your cron jobs are properly configured.

## Webhooks

• This module provides webhook endpoints that RaiseDonors can use to notify your Drupal site when donor data changes:
• `https://my_drupal_site.com/raisedonors/webhook/donor-created` - Called when a new donor is created in RaiseDonors
• `https://my_drupal_site.com/raisedonors/webhook/donor-updated` - Called when an existing donor is updated in RaiseDonors
• `https://my_drupal_site.com/raisedonors/webhook/donor-deleted` - Called when a donor is deleted in RaiseDonors

**Important:**

• Replace `https://my_drupal_site.com` with the actual URL of your Drupal website
• Ensure these URLs are fully qualified and accessible from the internet
• The URLs must include the full domain name when configuring webhooks in the RaiseDonors platform
• Configure a webhook security token in both RaiseDonors and in this module's settings to secure webhook endpoints

### Setting Up Webhook Security:

1. Go to your RaiseDonors account settings and locate webhook configuration
2. Create a security token for your webhook
3. Enter the same security token in the module settings form at `/admin/config/integrations/raisedonors`
4. This token will be included in the webhook payload and validated by Drupal to ensure only legitimate requests are processed

## Uninstallation

When the module is uninstalled, it will:

1. Remove all custom fields created by the module
2. Remove all permissions related to the module
3. Delete all module configuration
4. Handle users as specified in the uninstallation settings (keep, disable, or delete)

## Security

This module follows Drupal 11 security best practices:

• API keys are stored securely using the Key module
• Webhook endpoints validate incoming requests using security tokens
• Webhook token validation uses hash_equals() for timing-safe comparison
• All user input is properly sanitized
• Code follows Drupal coding standards and PHPStan level 8 compliance

## Troubleshooting

• Ensure your RaiseDonors API credentials are correct
• Check the Drupal logs for detailed error messages
• Verify that webhooks are properly configured in RaiseDonors
• Confirm that the security token is the same in both RaiseDonors and the module settings
• If automatic syncs aren't running, check your Drupal cron configuration
• For manual sync issues, ensure your PHP execution time and memory limits are sufficient

## Support

For issues and feature requests, please use the [issue queue](https://www.drupal.org/project/issues/raisedonors) on Drupal.org.

## Testing API & Webhooks Locally
If using DDEV, see https://ddev.readthedocs.io/en/stable/users/topics/sharing/