monorepo/native/wordpress/maple-carts-wp/README.md

# Maple Carts

A lightweight abandoned cart recovery plugin for WooCommerce. No bloat, no tracking, no upsells.

## Features

- **Cart Tracking** - Captures email and cart data on checkout via AJAX
- **Automated Emails** - Configurable email sequences with customizable delays
- **Coupon Generation** - Auto-generate unique discount codes per email
- **Cart Recovery** - Tokenized URLs restore cart contents with one click
- **SMTP Compatible** - Works with any SMTP plugin (Mailjet, Mailchimp, SendGrid, etc.)
- **Privacy Focused** - No external requests, no analytics, no phone-home behavior
- **HPOS Compatible** - Works with WooCommerce High-Performance Order Storage
- **Blocks Compatible** - Works with WooCommerce Checkout Blocks

## Email Modes

Maple Carts supports two email modes:

### Built-in Emails (Default)
Send timed recovery emails directly through WordPress/SMTP. Configure email templates with delays (1 hour, 24 hours, 3 days, etc.) and the plugin sends them automatically.

### Mailjet Sync
Instead of sending emails directly, sync abandoned cart data to Mailjet as contact properties. This allows you to:
- Use Mailjet's powerful automation builder
- Create complex multi-step workflows
- Combine with other Mailjet segments and triggers
- Use Mailjet's analytics and A/B testing

#### Mailjet Contact Properties
When a cart is abandoned, these properties are synced to the contact in Mailjet:

| Property | Type | Description |
|----------|------|-------------|
| `maple_has_abandoned_cart` | Boolean | True when cart is abandoned, false when recovered |
| `maple_cart_total` | Float | Cart total value |
| `maple_cart_currency` | String | Currency code (USD, EUR, etc.) |
| `maple_cart_product_count` | Integer | Number of items in cart |
| `maple_cart_product_names` | String | Product names (comma separated) |
| `maple_cart_categories` | String | Product categories (comma separated) |
| `maple_cart_value_level` | String | `low` (<$20), `medium` ($20-80), `high` ($80+) |
| `maple_abandonment_type` | String | `checkout` (email only) or `payment` (filled billing) |
| `maple_cart_recovery_url` | String | Recovery URL with coupon and UTM tracking |
| `maple_cart_first_seen_at` | DateTime | When cart was first created (funnel entry) |
| `maple_cart_abandoned_at` | DateTime | When the cart was abandoned |
| `maple_cart_coupon_code` | String | Generated coupon code (if enabled) |
| `maple_customer_first_name` | String | Customer first name |
| `maple_customer_last_name` | String | Customer last name |
| `maple_recovered_via` | String | Attribution: `mailjet`, `email_link`, `direct`, `purchase` |

#### Example Mailjet Automation Conditions
```
maple_has_abandoned_cart equals true
maple_cart_total is greater than 50
maple_cart_value_level equals high
maple_cart_categories contains "Electronics"
maple_abandonment_type equals payment
maple_cart_abandoned_at is less than 24 hours ago
```

#### Recovery Attribution
Recovery URLs include UTM parameters for analytics attribution:
- Built-in emails: `utm_source=maple_carts&utm_medium=email&utm_campaign=cart_recovery`
- Mailjet: `utm_source=mailjet`

The plugin tracks recovery source both in the database and syncs to Mailjet:

| `maple_recovered_via` | Description |
|-----------------------|-------------|
| `mailjet` | Recovered via Mailjet automation email |
| `builtin_email` | Recovered via built-in email system |
| `email_link` | Recovered via generic/shared recovery link |
| `direct` | Customer returned without clicking a recovery link |
| `purchase` | Direct purchase (cart was never abandoned) |

This enables full recovery performance analysis across channels.

#### Setup
1. Go to Settings → Email Mode → Mailjet Sync
2. Enter your Mailjet API Key and Secret Key
3. Click "Test Connection" to verify credentials
4. Click "Setup Contact Properties" to create the properties in Mailjet
5. Save settings
6. In Mailjet, create a Segment using `maple_has_abandoned_cart equals true`
7. Use that Segment in your automation workflows

## Developer Hooks

Maple Carts provides action hooks for integrations like Facebook CAPI, custom analytics, etc.

### Available Actions

```php
// Fires whenever a cart is created or updated (for retargeting pixels)
do_action( 'maple_carts_cart_updated', $cart );

// Fires when a cart is marked as abandoned
do_action( 'maple_carts_cart_abandoned', $cart_id, $cart );

// Fires when an abandoned cart is recovered
do_action( 'maple_carts_cart_recovered', $cart_id, $cart );

// Fires when a cart converts to an order
do_action( 'maple_carts_cart_converted', $cart_id, $cart );
```

### Example: Facebook CAPI Integration

```php
add_action( 'maple_carts_cart_updated', function( $cart ) {
    // Send AddToCart event to Facebook CAPI
    if ( ! empty( $cart->email ) ) {
        // Your Facebook CAPI code here
    }
});

add_action( 'maple_carts_cart_abandoned', function( $cart_id, $cart ) {
    // Send custom event for abandoned cart
}, 10, 2 );
```

## GDPR Compliance

Maple Carts includes built-in GDPR compliance features:

### Privacy Tools Integration
- **Data Export**: Integrates with WordPress Privacy Tools (Tools → Export Personal Data)
- **Data Erasure**: Integrates with WordPress Privacy Tools (Tools → Erase Personal Data)
- **Privacy Policy**: Adds suggested text to your Privacy Policy page

### Consent Management
- **Optional Consent Checkbox**: Enable in Settings → Privacy to require explicit opt-in
- **Consent Text**: Customizable checkbox label
- **Session-based Consent**: Consent is remembered for the checkout session

### User Rights
- **Unsubscribe**: One-click unsubscribe link in every email
- **Delete Data**: Optional one-click data deletion link in emails (enable in Settings → Privacy)
- **Automatic Cleanup**: Data automatically deleted after configurable retention period (default 90 days)

**Note**: The "Delete my data" link is optional and disabled by default. Enable it in Settings → Privacy if you have customers in the EU or other regions with data deletion requirements.

### Data Collected
When enabled, Maple Carts collects:
- Email address, name, phone number
- Billing address
- Cart contents and total
- IP address and browser information

All data is stored locally in your WordPress database. No data is sent to external servers.

## Requirements

- WordPress 5.8+
- WooCommerce 5.0+
- PHP 7.4+

## Installation

1. Upload the `maple-carts` folder to `/wp-content/plugins/`
2. Activate the plugin through the 'Plugins' menu in WordPress
3. Go to **Maple Carts > Settings** to configure
4. Go to **Maple Carts > Email Templates** to activate your email sequence

## Email Placeholders

Use these in your email templates:

| Placeholder | Description |
|------------|-------------|
| `{{customer_name}}` | Customer's first name |
| `{{customer_email}}` | Customer's email address |
| `{{cart_contents}}` | HTML table of cart items |
| `{{cart_total}}` | Formatted cart total |
| `{{product_names}}` | Comma-separated product names |
| `{{recovery_url}}` | Link to restore cart |
| `{{coupon_code}}` | Generated coupon code |
| `{{coupon_amount}}` | Discount amount (e.g., "10%" or "$5.00") |
| `{{coupon_expires}}` | Days until coupon expires |
| `{{site_name}}` | Your site name |
| `{{unsubscribe_link}}` | Unsubscribe link |
| `{{delete_data_link}}` | GDPR data deletion link (only shown if enabled in settings) |

## SMTP Integration

Maple Carts uses WordPress's native `wp_mail()` function, which means it automatically works with any SMTP plugin:

- **Mailjet** - Install "Mailjet for WordPress" plugin
- **Mailchimp/Mandrill** - Install "Mailchimp Transactional Email" plugin  
- **SendGrid** - Install "SendGrid" plugin
- **Amazon SES** - Install "WP Mail SMTP" and configure SES
- **Any SMTP** - Use "WP Mail SMTP" or similar

Just install and configure your preferred SMTP plugin - Maple Carts will use it automatically.

## Database Tables

The plugin creates 3 custom tables:

- `wp_maple_carts` - Abandoned cart data
- `wp_maple_carts_emails` - Email templates
- `wp_maple_carts_email_log` - Sent email history

## Hooks & Filters

### Actions

```php
// After a recovery email is sent
do_action( 'maple_carts_email_sent', $email_data, $subject );
```

### Filters

```php
// Modify email placeholders
add_filter( 'maple_carts_email_replacements', function( $replacements, $email_data ) {
    $replacements['{{custom}}'] = 'Custom Value';
    return $replacements;
}, 10, 2 );

// Modify email before sending
add_filter( 'maple_carts_before_send_email', function( $email ) {
    // $email contains: to, subject, body, headers
    return $email;
} );
```

## Comparison with Original Plugin

| Feature | Original (CartFlows) | Maple Carts |
|---------|---------------------|-------------|
| Size | 4.2 MB | ~150 KB |
| PHP Files | 64 | 8 |
| Lines of Code | 17,205 | ~2,500 |
| External Requests | Yes (analytics) | None |
| React Admin | Yes (1.8 MB) | No (PHP) |
| NPS Surveys | Yes | No |
| Upsells | Yes | No |

## License

GPL v2 or later

## Changelog

### 1.0.0
- Initial release