=== Shipping Guard - Advanced Shipping Suite, Weight Based Shipping, Zero Emission & Protection ===
Contributors: Dominopress
Tags: woocommerce shipping, weight based shipping, shipping insurance, zero emission delivery, express shipping, delivery date, package protection, claims management, free shipping bar
Requires at least: 5.8
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 2.2.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

The ultimate WooCommerce logistics and shipping protection command center: Self-funded parcel insurance, weight-based rules, 1-click replacement orders, delivery estimates with urgency countdown, and conversion-boosting free shipping bars.

== Description ==

Welcome to **Shipping Guard**, the most powerful, modular, and comprehensive logistics suite ever engineered for WooCommerce. 

Rather than paying expensive monthly subscriptions or surrendering up to 40% of insurance revenue to third-party providers (like Route or Navidium), **Shipping Guard** puts you in total control. Build your own high-margin internal insurance fund, automate package weight calculations, provide estimated arrival dates with psychological countdown urgency, and offer seamless 1-click claim resolutions directly from your store.

---

### 🌟 Why Top WooCommerce Stores Choose Shipping Guard

1. **Keep 100% of Protection Revenue**: Unlike 3rd-party insurance plugins that keep customer fees, ShippingGuard deposits 100% of customer protection fees straight into your store's bank account.
2. **Instant 1-Click Replacement Orders**: Resolve customer claims in 10 seconds. Generate 100% discounted replacement WooCommerce orders with one click directly from the claims dashboard.
3. **GDPR & EU Consumer Law Compliant**: Easily toggle between pre-selected (checked) and explicit opt-in (unchecked) protection states to respect regional regulations.
4. **Dual Widget Layouts & Visual Customizer**: Choose between high-converting **Card Box** or minimalist **Compact Single-Line** widgets, matching your store's exact brand aesthetic.
5. **Real-Time Delivery Urgency**: Drive immediate checkout conversions with live countdown timers (*"Order within 2h 15m for delivery by Thursday"*).
6. **Loss Ratio Business Intelligence**: Track your insurance loss ratio, net retained profit, and incident breakdown across carrier damage, lost parcels, and porch piracy.

---

== Detailed Feature Breakdown ==

### 🛡️ 1. Shipping Protection & Package Insurance Engine

Give your customers complete peace of mind while building a lucrative, self-funded risk protection fund.

* **Flexible Fee Models**:
  * **Fixed Fee**: Charge a flat fee per order (e.g., $2.99 per shipment).
  * **Percentage Fee**: Bill a dynamic percentage of the cart subtotal (e.g., 2.5% of order value).
  * **Minimum & Maximum Caps**: Set safety floors and ceilings (e.g., min $1.00 floor, max $5.00 cap) so small orders aren't overcharged and large orders stay reasonable.
  * **Tiered Range Rules**: Create subtotal brackets (e.g., $0–$50: $1.50 fee; $50–$100: $2.50 fee; $100+: $4.00 fee).
* **Category Scoping**: Protect all products globally, or restrict coverage only to specific high-risk categories (e.g., Electronics, Jewelry, Fragile Glassware).
* **Compliance & Default Opt-In Toggle**:
  * **Checked by Default (Opt-Out)**: Delivers 70%+ customer adoption and maximizes protection revenue.
  * **Unchecked by Default (Explicit Opt-In)**: Fully compliant with EU, UK, and Australian consumer protection laws.
* **Store-Funded Free Protection Threshold**:
  * *Example*: Set free protection at $150. Carts above $150 receive complimentary protection automatically funded by your store (*"FREE VIP Protection"*), drastically lowering cart abandonment on premium orders.
* **Mandatory Protection Lock Threshold**:
  * *Example*: Set mandatory lock at $500. High-value shipments automatically lock protection on so customers cannot opt out, safeguarding your store against high-cost lost parcel disputes.
* **Tax Exemption Controls**: Configure protection fees as **Tax-Exempt** (standard regulatory status for insurance) or **Taxable** with custom WooCommerce tax classes.
* **"What is Covered?" Interactive Modal**:
  * Displays a sleek modal explaining coverage for **Transit Damage**, **Lost Shipments**, and **Porch Piracy / Doorstep Theft**.

---

### 📦 2. Claims Management & Automated Resolution Center

Transform stressful lost parcel support tickets into 5-star customer experiences.

* **1-Click Free Replacement Orders**:
  * Approve a claim and click **"Replace Order"**. ShippingGuard instantly clones the customer's items into a new WooCommerce order with 100% discount, zero shipping, claim reference notes, and customer addresses pre-filled.
* **Automated Customer Status Emails**:
  * Fully automated, responsive transactional email alerts sent when claims are **Received**, **Approved**, **Rejected**, or **Refunded**.
* **Guest & Unregistered Customer Claims**:
  * Unregistered buyers can file claims using **Order Number + Billing Email** verification. No WordPress account creation required.
* **Public Claims Portal Shortcode**:
  * Place `[shippingguard_claims]` on any page to build a dedicated, branded customer claims portal (e.g., `yourstore.com/claims`).
* **Instant Claim Tracking Shortcode**:
  * Place `[shippingguard_track]` anywhere to let customers look up claim status in real-time.
* **Centralized Admin Claims Dashboard**:
  * Search, filter by status, inspect customer-uploaded photo evidence, update claim statuses, and export selected claims to CSV with one click.

---

### ⚖️ 3. Advanced Weight & Volumetric (DIM) Logistics Engine

Eliminate shipping margin leaks on heavy, bulky, or irregular parcels.

* **Mass-Based Incremental Pricing**:
  * Charge a base handling fee plus a fixed rate per unit of weight (lbs, kg, oz, g).
  * *Example*: $5.00 Base Handling + $1.50 per kg of cart weight.
* **Free Weight Allowance (Threshold)**:
  * Offer standard shipping for the first X units of weight (e.g., first 5 lbs free) and only charge for excess weight.
* **Excess Charge Mode Logic**:
  * **Extra Weight Only**: A 7 lb order with a 5 lb allowance only bills for the 2 lbs of excess.
  * **Full Weight Once Exceeded**: A 7 lb order crossing the 5 lb threshold bills for all 7 lbs.
* **Volumetric (Dimensional) Weight Math**:
  * Calculate dimensional weight using standard formula: `(Length × Width × Height) / Divisor`.
  * *Example*: Bill for large but lightweight items (e.g., foam rollers, pillows) so carriers don't eat your margins.
* **Automated Multi-Package Splitting**:
  * Automatically divide oversized carts into multiple boxes when cart weight crosses your maximum single-box threshold (e.g., split at 30 kg).
* **Product-Level Custom Fulfillment Weights**:
  * Set a dedicated packaging fulfillment weight on specific products without corrupting standard WooCommerce product weight.
* **Product-Level Fixed Handling Surcharges**:
  * Add individual handling fees to specific oversized or fragile items.
* **Hero Product Free Shipping Override**:
  * Designate specific promotional items that grant global free shipping whenever present in the cart.

---

### 🚚 4. Estimated Delivery Dates (EDD) & Service Levels

Reduce "Where is my order?" support inquiries by up to 40% with transparent delivery timelines.

* **Business Days Calculation Engine**:
  * Calculates dynamic arrival date ranges based on min and max transit days, automatically skipping non-working weekend days.
* **Live Urgency Cutoff Countdown Timer**:
  * Display a live countdown on single product pages: *"Order within **2h 34m** to receive it by **Friday, Nov 12th**!"*
* **Holiday & Warehouse Blackout Dates**:
  * Input comma-separated dates (e.g., `2026-12-25, 2027-01-01`) to automatically skip warehouse closures and carrier holidays when estimating transit.
* **Flexible Widget Positioning**:
  * Display estimates on product pages: Above Add-to-Cart, Below Add-to-Cart, Main Summary, or Product Meta. Also appears automatically on Checkout.
* **Priority Express Delivery Lanes**:
  * Offer a premium "Jump the Queue / Express Lane" upgrade at checkout for an extra fee.

---

### 🌱 5. Sustainability & Zero-Emission Eco-Delivery

Position your brand as environmentally conscious with customer-funded carbon offsets.

* **Green Carbon Offset Contributions**:
  * Allow customers to contribute a small offset fee (e.g., $0.50) at checkout to neutralize their parcel's carbon footprint.
* **Sustainability Insights**:
  * Live tracking of total carbon saved (kg of CO2) and eco-friendly delivery adoption rates in your Analytics dashboard.

---

### 📈 6. Conversion-Gamified Free Shipping Bar

Increase Average Order Value (AOV) by giving shoppers a visual spending target.

* **Live Subtotal Goal Tracker**:
  * Shows customers how close they are to free shipping (e.g., *"$18.50 away from FREE Shipping"*).
* **Real-Time AJAX Synchronization**:
  * Automatically animates and updates progress without page reloads when products are added or removed from the cart or mini-cart.
* **Display Positions**:
  * Choose between a modern **Floating Bottom Snackbar** or a **Fixed Top Announcement Bar**.

---

### 📊 7. Enterprise Analytics & Loss Ratio Intelligence

Evaluate the profitability and health of your protection program with real-time enterprise metrics.

* **Claims Loss Ratio Tracker**:
  * Calculates `Total Claim Payouts ÷ Protection Revenue`. Shows healthy green status under 20% and warns merchants if losses exceed 25%.
* **Net Protection Profit & Margin**:
  * Displays retained net profit after accounting for approved claims.
* **Incident Classification Breakdown**:
  * Visual distribution bars showing exact counts and percentages for:
    * **Damaged in Transit**
    * **Lost / Carrier Vanished**
    * **Porch Piracy & Doorstep Theft**
    * **Other Shipping Issues**
* **Top Protected Products**:
  * Identify which catalog products are most frequently insured by your customers.
* **Custom Date Range Filtering**:
  * Instant presets for Last 7 Days, 30 Days, 90 Days, or Custom Date Picker.

---

== Shortcode Reference Guide ==

### `[shippingguard_claims]`
Embeds the complete Customer Claims Resolution Portal on any page or post. Logged-in customers see their claim history; guest customers can look up claims using Order ID + Billing Email.

*Example Page*: Create a page at `yoursite.com/file-claim` and insert `[shippingguard_claims]`.

### `[shippingguard_track]`
Renders a lightweight claim tracking lookup form where customers can enter their Order Number and Email to check current claim status (Pending, Approved, Rejected, Refunded).

---

== Competitor Comparison ==

| Feature | ShippingGuard | Route | Navidium | ShipTection |
| :--- | :---: | :---: | :---: | :---: |
| **Keep 100% of Protection Fees** | ✅ **YES** | ❌ No (Kept by Route) | ✅ Yes | ❌ Revenue share |
| **Monthly Subscription Required** | ❌ **NO ($0 Free)** | ❌ Revenue cut | ❌ Paid app fee | ❌ Monthly fee |
| **1-Click Replacement Order Creation** | ✅ **YES** | ❌ Portal only | ⚠️ Manual | ⚠️ Manual |
| **EU GDPR Unchecked Opt-In Mode** | ✅ **YES** | ❌ Third-party forced | ⚠️ Custom code | ❌ Pre-selected only |
| **Dual Card / Compact Layouts** | ✅ **YES** | ❌ Fixed widget | ⚠️ Limited | ❌ Fixed widget |
| **Urgency Cutoff Countdown Timer** | ✅ **YES** | ❌ No | ❌ No | ❌ No |
| **Loss Ratio Business Intelligence** | ✅ **YES** | ❌ No | ⚠️ Basic | ❌ No |
| **Integrated Weight & DIM Engine** | ✅ **YES** | ❌ No | ❌ No | ❌ No |
| **Free Shipping Conversion Bar** | ✅ **YES** | ❌ No | ❌ No | ❌ No |
| **Customer Email Notifications** | ✅ **YES** | ⚠️ Route app only | ⚠️ Basic | ⚠️ Basic |

---

== Installation ==

1. Upload the `shippingguard` folder to your `/wp-content/plugins/` directory (or install via the WordPress Plugins menu).
2. Activate the plugin through the **Plugins** screen in WordPress.
3. Go to **ShippingGuard** in your WordPress admin sidebar.
4. Enable the modules you need (Shipping Protection, Weight Rules, Delivery Dates, Free Shipping Bar).
5. Configure your preferred fee structure and save settings.

---

== Frequently Asked Questions ==

= How do I collect insurance revenue? =
Protection fees are added directly as a WooCommerce cart fee during checkout. When the customer completes payment, 100% of the fee goes straight into your store's merchant account (Stripe, PayPal, etc.). There are no middlemen, no revenue sharing, and no third-party cuts.

= Is ShippingGuard compliant with EU/UK consumer regulations? =
Yes! In *ShippingGuard > Shipping Protection > Checkout Widget & Compliance Styling*, set the **Default Selection State** to **"Unchecked (Explicit Opt-in)"**. This ensures customers in the European Union and UK must actively click to opt-in, keeping your store fully compliant with consumer protection and GDPR laws.

= How does the 1-Click Replacement Order feature work? =
When a customer files a claim for a broken or lost item and you approve it, click the **"Replace Order"** button in the Claims dashboard. ShippingGuard automatically creates a new WooCommerce order with the same line items at $0.00, sets shipping to Free, adds internal reference notes linking to the original claim, and opens the new order for immediate fulfillment.

= Can guest customers without an account submit claims? =
Yes. Unregistered guest buyers simply enter their Order Number and the Billing Email address used at checkout. ShippingGuard verifies the email against the WooCommerce order records before accepting the claim.

= Can I customize the widget colors and border radius? =
Yes. ShippingGuard includes an integrated styling customizer where you can select between **Card Box** and **Compact Minimal** layouts, customize border radius from 0px (sharp) to 16px (soft round), and choose your primary brand theme colors.

= Does ShippingGuard work with WooCommerce Blocks? =
Yes. ShippingGuard includes native Store API integration for WooCommerce Block-based Cart and Checkout pages, ensuring real-time fee recalculation when the toggle is clicked.

= What units of weight and dimensions are supported? =
ShippingGuard automatically syncs with your native WooCommerce settings and supports kilograms (kg), pounds (lbs), ounces (oz), grams (g), centimeters (cm), millimeters (mm), meters (m), and inches (in).

= Can I waive protection fees on high-value orders? =
Yes! Use the **Store-Funded Free Protection Threshold** setting (e.g., $150). When a cart reaches that amount, protection is automatically applied for $0.00 as a complimentary gift to the customer.

---

== Screenshots ==

1. `screenshot-1.png`: **Shipping Protection Checkout Widget** (Card layout with "What's covered?" modal trigger).
2. `screenshot-2.png`: **Claims Management Center** with 1-click replacement order action and customer email lookup.
3. `screenshot-3.png`: **Claims Incident Intelligence & Loss Ratio Dashboard** in Analytics.
4. `screenshot-4.png`: **Estimated Delivery Date Widget** with live urgency cutoff countdown.
5. `screenshot-5.png`: **Logistics Settings Command Center** with styling customizer and threshold automation.

---

== Changelog ==

= 2.2.4 =
* FIX: Resolved fatal infinite loop in delivery date business days calculation (`add_business_days`).
* FIX: Gated delivery date validation to prevent checkout lockout on free/standard checkouts.
* FIX: Decoupled custom fulfillment weight from core catalog product weight to prevent data corruption.
* FIX: Corrected settings URL in plugin action links on plugins.php.
* FIX: Removed manual multipart content-type in Axios to preserve form boundary for photo uploads.
* FIX: Captured both shipping method IDs in analytics queries to accurately report all logistics revenue.
* FIX: Gated global root mount container behind Pro check to avoid empty DOM elements.
* NEW: Added Opt-in default toggle (Checked vs Unchecked) for EU/UK GDPR compliance.
* NEW: Added Widget layout customizer with Card Box and Compact Minimal modes, custom radius, and theme colors.
* NEW: Added interactive "What is covered?" customer coverage popover modal.
* NEW: 1-Click Free Replacement Order creation directly from approved claims dashboard.
* NEW: Automated transactional emails for customer claim submission, approval, rejection, and refunds.
* NEW: Guest claim submissions with email verification and dedicated portal shortcodes (`[shippingguard_claims]`, `[shippingguard_track]`).
* NEW: Loss ratio intelligence (<20% healthy benchmark) and incident classification breakdown in Analytics.
* NEW: Live urgency cutoff countdown timer and holiday blackout skipping on Estimated Delivery Dates.
* NEW: Store-funded free protection threshold and high-value mandatory protection lock.
* NEW: Real-time AJAX subtotal event listeners on Free Shipping Bar.

= 2.2.2 =
* IMPROVED: Strict Frontend Gating for all Premium modules.
* NEW: Centralized "Feature & Bug" portal linking to DominoPress support.
* FIXED: Module synchronization issue where disabled tools lingered on checkout.
* FIXED: REST API endpoint initialization for internal suite requests.

= 2.2.1 =
* FIX: Resolved Fatal Error during activation/refresh logic.
* NEW: Advanced 3D Box Inventory UI with precision L X W X H inputs.
* NEW: Real-time Site URL and User meta for feedback portal.
* IMPROVED: Repository SEO and documentation.
