=== Delveant Form Suite ===
Contributors: kovaion
Tags: form builder, contact form, CRM, lead capture, form
Requires at least: 6.2
Tested up to: 7.0
Requires PHP: 8.1
Stable tag: 1.0.1
License: GPL v2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Complete form management suite with drag-and-drop builder and secure Delveant CRM integration.

== Description ==

**Delveant Form Suite** is a WordPress form builder plugin that connects your forms directly to the Delveant CRM. It is designed around a strict server-to-server security model — API credentials never leave the server and are never exposed to the browser.

= Key Features =

* **Drag-and-drop form builder** — Create forms with 17 field types: Text, Email, Phone, Number, Textarea, Dropdown, Radio, Checkbox, Hidden, File Upload, Date, URL, Acceptance, HTML Block, Section Break, Container Block, and Submit.
* **Secure CRM integration** — Form submissions are forwarded to Delveant CRM server-to-server using OAuth 2.0. Tokens are stored AES-256-CBC encrypted and never exposed to the browser or any REST response.
* **Third-party form plugin integrations** — Route submissions from Contact Form 7, Gravity Forms, WPForms, Elementor Pro Forms, and Fluent Forms to Delveant CRM without rebuilding your forms.
* **Spam protection** — Honeypot, Google reCAPTCHA v3, Google reCAPTCHA v2, and Cloudflare Turnstile.
* **Submission logging** — Browse, search, and export form submissions from the WordPress admin.
* **Email notifications** — Admin notification and user auto-response emails with customisable HTML templates and template tags.
* **Gutenberg block** — Embed any form using the native Delveant Form block.
* **Shortcode support** — `[delveant-form id="X"]`
* **Import / export** — Export and import forms as JSON.
* **Rate limiting** — IP-based, configurable per-hour submission limits.

= Privacy & Data Collection =

This plugin collects and processes the following data:

* **Form submission data** — field values entered by visitors, stored in the WordPress database and optionally forwarded to Delveant CRM.
* **IP addresses** — stored locally with each submission for spam and fraud review; also stored as a SHA-256 hash in the rate-limiting table. The plain IP is stored in the submissions log only and is **not** forwarded to Delveant CRM or any other external service.
* **User agent strings** — the visitor's browser and OS identifier, stored with each submission.
* **Screen resolution** — the pixel dimensions of the visitor's screen (e.g. `1920x1080`), collected client-side at submission time and stored with each submission. Forwarded to Delveant CRM when CRM integration is enabled.
* **Browser language** — the visitor's preferred browser language (e.g. `en-US`), collected client-side at submission time and stored with each submission. Forwarded to Delveant CRM when CRM integration is enabled.
* **Tracking parameters** — UTM parameters (`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`), Google Ads click IDs (`gclid`), Facebook/Meta click IDs (`fbclid`), and Matomo visitor/user IDs, captured client-side when present and stored with submissions.

See the **External Services** section for details on third-party data transmission.

== External Services ==

This plugin communicates with the following external services. By enabling the relevant features, you agree to each service's terms and privacy policy.

= Delveant CRM =

This plugin connects to the Delveant CRM API to authenticate administrator credentials and to forward form submission data. No data is sent until the site administrator explicitly configures the integration.

**Allowed API domains:** All CRM requests are restricted to `*.delveant.ai`, `*.delveant.com`, and `*.delveant.cloud`. The default production domain is `coreapi.delveant.ai`. The API base URL can be overridden for development or staging purposes by defining `DELVEANT_FORM_SUITE_API_BASE` in `wp-config.php`; the override is still validated against the above domain list. Administrators can also configure a per-form or per-integration **Endpoint Override** (in the form builder's CRM tab or in the Integrations screen) to route a specific form's submissions to an alternative Delveant API endpoint; this endpoint is also validated against the same domain list.

**1. OAuth authentication**

* **Endpoint:** `https://coreapi.delveant.ai/api/v1/external/auth/token`
* **When data is sent:** Once, when a site administrator enters their Client ID and Client Secret in Settings and clicks "Connect to CRM."
* **Data transmitted:** The administrator's OAuth Client ID and Client Secret.
* **Purpose:** Exchanges the administrator credentials for an access token and refresh token that are then stored encrypted in the WordPress database.

**2. Token refresh**

* **Endpoint:** `https://coreapi.delveant.ai/api/v1/external/auth/refresh`
* **When data is sent:** Automatically in the background when the stored access token has expired and a form submission triggers a CRM call.
* **Data transmitted:** The stored OAuth refresh token.
* **Purpose:** Obtains a new access token without requiring the administrator to re-enter credentials.

**3. Lead submission**

* **Endpoint:** `https://coreapi.delveant.ai/api/v1/externallead` (or the configured endpoint override, if set)
* **When data is sent:** On every form submission where CRM integration is enabled for that form, and when the administrator clicks "Test Connection" in Settings.
* **Data transmitted on form submission:**
  * Form field values (as mapped to CRM fields)
  * Page URL and HTTP referrer
  * Form type, lead source, and campaign identifier (as configured by the administrator)
  * Submission timestamp
  * UTM parameters (`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`), Google Ads click ID (`gclid`), and Facebook/Meta click ID (`fbclid`), if present in the page URL at submission time
  * Matomo visitor ID and user ID, if the Matomo analytics tracker is active on the page (see Matomo section below)
  * Visitor screen resolution (e.g. `1920x1080`) and browser preferred language (e.g. `en-US`), collected client-side
  * The site URL, plugin version, and WordPress version (sent as HTTP request headers: `X-Site-URL`, `X-Source`, and `User-Agent`)
  * A source identifier string (`delveant-form-suite-wp`)
  * **Note:** The visitor's IP address is stored locally in WordPress only and is **not** included in the CRM payload.
* **Data transmitted on test connection:** A source identifier string (`delveant-form-suite-wp-test`) in the request body, plus the site URL, plugin version, and WordPress version in HTTP request headers. No visitor or form data is sent.

* **Service provider:** Delveant
* **Privacy Policy:** https://delveant.com/privacy-policy/
* **Terms of Service:** https://delveant.com/terms-and-conditions/

= Google reCAPTCHA =

When Google reCAPTCHA v3 or v2 is enabled in Settings > Spam Protection, the plugin loads Google's reCAPTCHA JavaScript on pages containing a form and verifies CAPTCHA responses server-side.

* **Frontend script loaded from:** `https://www.google.com/recaptcha/api.js`
* **Server-side verification endpoint:** `https://www.google.com/recaptcha/api/siteverify`
* **When data is sent:** On every page load that displays a form (the Google JS runs and may fingerprint the visitor); on every form submission (server-side verification call).
* **Data transmitted to Google:** Visitor IP address, CAPTCHA response token.
* **Service provider:** Google LLC
* **Privacy Policy:** https://policies.google.com/privacy
* **Terms of Service:** https://policies.google.com/terms

= Cloudflare Turnstile =

When Cloudflare Turnstile is enabled in Settings > Spam Protection, the plugin loads Cloudflare's Turnstile JavaScript on pages containing a form and verifies challenge responses server-side.

* **Frontend script loaded from:** `https://challenges.cloudflare.com/turnstile/v0/api.js`
* **Server-side verification endpoint:** `https://challenges.cloudflare.com/turnstile/v0/siteverify`
* **When data is sent:** On every page load that displays a form (the Turnstile JS runs and may fingerprint the visitor); on every form submission (server-side verification call).
* **Data transmitted to Cloudflare:** Visitor IP address, Turnstile response token.
* **Service provider:** Cloudflare, Inc.
* **Privacy Policy:** https://www.cloudflare.com/privacypolicy/
* **Terms of Service:** https://www.cloudflare.com/website-terms/

= Matomo Analytics (optional, no direct connection) =

If the Matomo analytics platform is already installed and active on your site, this plugin reads Matomo tracking identifiers at form-submission time. This plugin makes no direct HTTP connection to any Matomo server. The data is collected client-side and included in the form submission sent to your own WordPress site, where it is stored in the submissions log and — if CRM integration is enabled — forwarded to Delveant CRM alongside the other submission data.

This behaviour only occurs when Matomo is present on the page. If Matomo is not installed on your site, no Matomo data is collected.

* **No direct connection made to:** Any Matomo server or matomo.org
* **When data is collected:** On every form submission, if the Matomo tracker is active on the page at that moment.
* **Data collected:**
  * **From the Matomo JavaScript tracker object** (`window.Matomo`): visitor ID (`matomo_visitor_id`) and user ID (`matomo_user_id`). These are read via `Matomo.getTracker().getVisitorId()` and `getUserId()`.
  * **From URL / form parameters** (if present at the time of submission): Matomo visitor cookie parameter (`_pk_id`) and Matomo visitor ID URL parameter (`_pk_vid`). These are only captured when explicitly passed as query parameters on the page URL; the plugin does not read Matomo cookies directly.
* **Where the data goes:** Stored in the local WordPress submissions log (if logging is enabled) and forwarded to Delveant CRM (if CRM integration is enabled for the form).
* **Service provider:** InnoCraft Ltd (Matomo)
* **Privacy Policy:** https://matomo.org/privacy-policy/
* **Terms of Service:** https://matomo.org/terms/

== Installation ==

= Automatic Installation =

1. In your WordPress admin, go to **Plugins > Add New**.
2. Search for **Delveant Form Suite**.
3. Click **Install Now**, then **Activate**.

= Manual Installation =

1. Download the plugin ZIP.
2. Go to **Plugins > Add New > Upload Plugin**.
3. Upload the ZIP and click **Install Now**, then **Activate**.

= Initial Setup =

1. Go to **Delveant Form Suite > Settings > CRM**.
2. Enter your Delveant **Client ID** and **Client Secret**, then click **Connect to CRM**.
3. (Optional) Configure spam protection under **Settings > Spam Protection**.
4. Go to **Delveant Form Suite > Add New** to create your first form.
5. Copy the generated shortcode and paste it into any page, post, or widget.

== Frequently Asked Questions ==

= Does the plugin require a Delveant account? =

The form builder, submission logging, and email notifications work without a Delveant account. The CRM integration — forwarding submissions to Delveant CRM — requires a Delveant account with OAuth credentials.

= Is my API token secure? =

Yes. OAuth tokens are stored AES-256-CBC encrypted in the WordPress options table. They are never serialised to the browser, never included in any REST API response, and never written to logs. Only server-side PHP decrypts and uses them at request time.

= Can I use the plugin without connecting to Delveant CRM? =

Yes. CRM integration is opt-in and configured per form. You can use the form builder, receive email notifications, and log submissions entirely within WordPress without connecting to any external service.

= Can I integrate my existing Contact Form 7 / Gravity Forms / WPForms forms? =

Yes. Go to **Delveant Form Suite > Connect Forms to CRM** and configure the integration for your existing form plugin. Submissions will be forwarded to Delveant CRM without requiring you to replace your existing forms.

= Does the plugin store personal data? =

When submission logging is enabled (the default), form field values, IP addresses, and user agents are stored in the WordPress database. You can disable logging under **Settings > Advanced**, and you can delete individual submissions or bulk-delete from the Submissions screen. See the **External Services** section for third-party data transmission.

= How do I translate the plugin? =

The plugin is fully internationalised. The text domain is `delveant-form-suite`. Place `.po`/`.mo` files in `wp-content/languages/plugins/` or use the Translate WordPress workflow at translate.wordpress.org.

== Changelog ==

= 1.0.0 =
* Initial release.

== Upgrade Notice ==

= 1.0.0 =
Initial release.

= 1.0.1 =
* Fixed form builder issues and added token refresh feature.
