wpgens points and rewards api

readme.txt

**Custom Point Actions & Integrations**

You can add custom point actions by using the `wpgens_loyalty_update_points` action. Here are some examples:

```php
// Award points for a custom action
function award_custom_points($user_id, $points, $description) {
    do_action(
        'wpgens_loyalty_update_points',
        $user_id,
        $points,
        'add',
        'custom_action',
        null,
        $description
    );
}

// Example: Award points for completing a quiz
add_action('quiz_completed', function($user_id, $quiz_id) {
    $points = 100; // Award 100 points
    $description = sprintf('Completed quiz #%d', $quiz_id);
    award_custom_points($user_id, $points, $description);
});

// Example: Award points for social media engagement
add_action('social_media_engagement', function($user_id, $platform, $action) {
    $points = 50; // Award 50 points
    $description = sprintf('Engaged on %s: %s', $platform, $action);
    award_custom_points($user_id, $points, $description);
});

// Example: Integration with another plugin
add_action('other_plugin_custom_event', function($user_id, $event_data) {
    // Calculate points based on event data
    $points = calculate_points_from_event($event_data);
    $description = sprintf('Completed %s', $event_data['event_name']);
    
    do_action(
        'wpgens_loyalty_update_points',
        $user_id,
        $points,
        'add',
        'other_plugin',
        $event_data['event_id'],
        $description
    );
});

// Example: Deduct points for a penalty
function deduct_points_penalty($user_id, $points, $reason) {
    do_action(
        'wpgens_loyalty_update_points',
        $user_id,
        $points,
        'deduct',
        'penalty',
        null,
        $reason
    );
}
```

**Integration Best Practices**

1. Always use meaningful `$source` values to track where points came from
2. Include relevant `$reference_id` when available (e.g. order ID, post ID)
3. Use descriptive `$description` for better tracking
4. Consider adding your own hooks to allow others to extend your integration
5. Test points updates in test mode first
6. Handle errors gracefully and log them if needed