=== CareHQ Connector ===
Contributors: victorydigitalplugins
Tags: carehq, crm, forms, care homes, gravity forms, wpforms, fluent forms, contact form 7, forminator, field mapping, crm integration
Requires at least: 6.0
Tested up to: 6.9
Requires PHP: 8.0
Stable tag: 3.6.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Connect WordPress forms to CareHQ CRM — intelligent field mapping, conditional routing, and UTM tracking for care home enquiry management.

== Description ==

**CareHQ Connector** bridges the gap between your WordPress contact forms and your [CareHQ CRM](https://carehq.co.uk) account. Enquiries submitted through your website are automatically routed to the right care home location, with all contact fields properly mapped — no copy-paste, no missed leads.

Whether you're running a single care home or managing a multi-site group, CareHQ Connector gives you a visual, no-code interface for configuring exactly how form data flows into CareHQ.

= Supported Form Plugins =

* **Gravity Forms**
* **WPForms**
* **Fluent Forms**
* **Forminator**
* **Contact Form 7**

= Key Features =

**Visual Workflow Builder**
See exactly how your form data flows to CareHQ before it goes live. Configure mappings in a clear, visual interface.

**Smart Field Mapping**
Map any form field to the corresponding CareHQ contact field. Supports text, email, phone, and custom fields.

**Conditional Routing**
Route enquiries to different CareHQ locations based on form field values — ideal for multi-home operators.

**UTM & Marketing Attribution**
Automatically captures UTM parameters (source, medium, campaign, term, content) and passes them to CareHQ so you know exactly where each lead came from.

**Submission Logging**
Every form submission is logged with its CareHQ response, making it easy to debug and audit.

**UK Phone Validation**
Automatic validation and formatting of UK phone numbers using the libphonenumber library, ensuring clean data reaches your CRM.

**Health Dashboard**
Real-time dashboard showing API connectivity status, recent submission results, and system health.

**Retry Queue**
Failed submissions are queued and automatically retried, so no enquiry is ever lost due to a temporary API outage.

= External Services =

This plugin connects to the **CareHQ CRM API** to submit contact enquiries. A CareHQ account with API credentials is required. Please review CareHQ's [Terms of Service](https://carehq.co.uk/terms) and [Privacy Policy](https://carehq.co.uk/privacy) before using this plugin, as form submission data (contact details) is transmitted to CareHQ's servers.

This plugin also connects to **app.formconnector.co.uk** to validate your plugin license key. License validation requests include your site URL and license key only — no personal data or form submissions are sent.

== Installation ==

1. Upload the `carehq-connector` folder to the `/wp-content/plugins/` directory, or install via the WordPress Plugins screen.
2. Activate the plugin through the **Plugins** menu in WordPress.
3. Navigate to **CareHQ Connector** in the WordPress admin menu.
4. Enter your license key on the **License** tab.
5. Enter your CareHQ API credentials (Account ID, API Key, API Secret) on the **Settings** tab.
6. Go to **Mappings** and configure field mapping for each of your forms.

= Getting Your CareHQ API Credentials =

1. Log in to your CareHQ account at [carehq.co.uk](https://carehq.co.uk).
2. Navigate to **Settings → API**.
3. Create or copy your Account ID, API Key, and API Secret.
4. Paste these into **CareHQ Connector → Settings**.

== Frequently Asked Questions ==

= Which form plugins are supported? =

Gravity Forms, WPForms, Fluent Forms, Forminator, and Contact Form 7. You only need to have at least one of these installed and active.

= Does this work with multi-site WordPress installations? =

Yes. The plugin can be activated per-site on a WordPress multisite network.

= Can I route enquiries to different care homes based on what the user selects? =

Yes. The conditional routing feature lets you define rules so that, for example, selecting a specific location in a dropdown sends the enquiry to the matching CareHQ home.

= What happens if the CareHQ API is temporarily unavailable? =

Submissions are queued and retried automatically. You can also view and manually retry failed submissions from the **Logs** screen.

= Is form submission data stored in WordPress? =

A log of each submission (including the CareHQ API response) is stored in your WordPress database for auditing purposes. Logs can be cleared from the admin panel.

= Does the plugin capture UTM parameters? =

Yes. If a visitor arrives via a tracked link (e.g. a Google Ads campaign), the UTM parameters are captured from the URL and included in the CareHQ contact record.

= What phone number formats are supported? =

The plugin uses the libphonenumber library to validate and normalise UK phone numbers. Both local (07xxx) and international (+44) formats are accepted.

= Is a CareHQ account required? =

Yes. This plugin is specifically designed to work with [CareHQ CRM](https://carehq.co.uk). You will need an active CareHQ account and API credentials.

== Screenshots ==

1. **Dashboard** — Overview of recent submissions, API health status, and quick links.
2. **Field Mapping** — Visual interface for mapping form fields to CareHQ contact fields.
3. **Conditional Routing** — Rule builder for routing submissions to different CareHQ locations.
4. **Submission Logs** — Detailed log of every form submission with CareHQ API response.
5. **Settings** — CareHQ API credentials and global plugin configuration.

== Changelog ==

= 3.6.0 =
* Added AI-powered field mapping suggestions ("Auto-map with AI") with a review/accept workflow
* Attribution page now reports on form submission metadata only (campaign/source/medium/landing page) — removed CRM-style lead status fields
* Improved loading states across AI mapping and attribution views
* Switched the admin UI to a neutral grey/white color theme
* Fixed WordPress admin styles overriding plugin select field sizing

= 3.4.0 =
* Improved retry queue with exponential back-off
* Added notification system for failed submissions
* Performance improvements to submission handler

= 3.3.0 =
* Added support for WPForms
* Improved UTM parameter capture across page sessions
* Bug fixes for Gravity Forms conditional logic compatibility

= 3.2.0 =
* Added health ping monitoring
* Improved webhook handler for CareHQ callbacks
* Added per-mapping enable/disable toggle

= 3.1.2 =
* Stability improvements
* Fixed edge case in phone number validation for international numbers

= 3.0.0 =
* Complete rebuild with modern Svelte 5 frontend
* New visual workflow builder
* Improved conditional routing with duplicate detection
* Enhanced error handling and logging
* Phone number validation with libphonenumber

== Upgrade Notice ==

= 3.4.0 =
Recommended update. Improves reliability of failed submission retries and adds email notifications for persistent failures.
