=== OptinBridge CRM – Consent & Contact Manager ===
Contributors: justo7
Tags: consent, crm, privacy, opt-in, whatsapp
Requires at least: 6.4
Tested up to: 7.1
Requires PHP: 8.0
Stable tag: 1.5.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Consent-first CRM for WordPress with auditable opt-ins, segmentation, privacy tools and CSV workflows for WhatsApp communications.

== Description ==

OptinBridge CRM – Consent & Contact Manager helps WordPress site owners collect voluntary registrations, organize contacts and keep an auditable history of consent for communications intended for WhatsApp.

The Community edition does not scrape groups, discover private phone numbers or send messages automatically. It focuses on consent capture, contact governance, segmentation, export/import and privacy workflows.

= Highlights =

* Public opt-in form with explicit unchecked consent checkbox.
* Public unsubscribe form.
* Consent Passport: auditable timeline of consent creation, renewal, revocation, blocking and related events.
* Duplicate prevention using normalized phone numbers.
* Administrative blocking that cannot be bypassed by a new public signup.
* Safe unblock flow: blocked → pending → new explicit opt-in → authorized.
* Groups, tags and saved campaign segments.
* Campaign audience preview and filtered CSV export.
* CSV import with preview, legal-origin confirmation and duplicate handling.
* Dashboard, logs and environment diagnostics.
* WordPress personal-data exporter and eraser integration.
* Individual anonymization and deletion tools.
* Gutenberg block and shortcodes.
* Authenticated REST API for authorized administrators.
* No mandatory external libraries or services.
* No built-in telemetry.

= What this plugin does NOT do =

* It does not access WhatsApp groups.
* It does not scrape or extract group participants.
* It does not discover private phone numbers.
* It does not collect contacts silently.
* It does not use unofficial WhatsApp Web automation.
* It does not send messages automatically in the Community edition.
* It does not guarantee legal compliance by itself.

The site operator remains responsible for choosing an appropriate legal basis, wording notices, defining retention, handling data-subject requests and using exported data appropriately.

== Installation ==

1. Upload and activate the plugin.
2. Open **OptinBridge CRM > Primeiros passos**.
3. Confirm the organization name, consent text and consent version.
4. Add the privacy-policy URL.
5. Select or create the public registration and unsubscribe pages.
6. Review the readiness indicator and diagnostics.
7. Create groups/tags as needed.
8. Run a test registration and unsubscribe before using the CRM with real contacts.

== Shortcodes ==

`[whatsapp_consent_form]`

Displays the public registration form.

`[whatsapp_consent_form group="group-slug"]`

Displays the registration form tied to one active group.

`[whatsapp_unsubscribe_form]`

Displays the public unsubscribe form.

== Blocks ==

The plugin registers a dynamic Gutenberg consent-form block. Existing shortcode integrations remain supported for backward compatibility.

== Consent Passport ==

Each contact can keep an auditable event history, including events such as:

* consent_created
* consent_renewed
* consent_revoked
* contact_blocked
* blocked_signup_attempt
* contact_unblocked
* contact_anonymized

Internal event codes remain stable for integrations while the WordPress admin displays friendly labels.

== Contact statuses ==

* `authorized` — has an active recorded opt-in.
* `cancelled` — the contact revoked/cancelled communications.
* `blocked` — administratively blocked and cannot reactivate through the public form.
* `pending` — not currently authorized; may become authorized after a new explicit public opt-in.

Cancelled and blocked contacts must not be treated as authorized recipients.

== Groups, Tags and Campaigns ==

Groups represent a primary campaign/source. Tags provide additional segmentation. Campaigns are saved audience definitions based on status, group and tag.

Campaigns do not send messages. They can preview the current audience, open filtered contacts and export a protected CSV for an authorized administrator.

== CSV Import ==

Preferred columns:

`nome;telefone;email;grupo;consentimento`

Example:

`Maria Silva;51999999999;maria@example.com;promocoes;sim`

Comma-separated files are also detected when possible.

The importer:

* rejects rows without affirmative consent;
* validates and normalizes phone numbers;
* avoids duplicates;
* can create a missing group;
* shows a preview before import;
* requires an administrative legal-origin confirmation;
* reports imported, updated and rejected rows;
* does not send any message after import;
* does not reactivate administratively blocked contacts.

== CSV Export ==

Exports require an authorized WordPress user and a valid nonce. Spreadsheet-formula prefixes are neutralized to reduce CSV Injection risk.

Campaign audience export includes only the contacts matching that campaign's saved filters at export time.

== REST API ==

Administrative read endpoints are available under `/wp-json/wcc/v1/` for backward compatibility.

Current routes include:

* `GET /contacts`
* `GET /groups`
* `GET /contacts/{id}/consent-events`

These routes may expose personal data and therefore require an authenticated WordPress user with the configured CRM management capability.

== Privacy ==

Depending on configuration and use, the plugin may store:

* name;
* phone number;
* optional email;
* group and tags;
* consent text and version;
* consent date/time;
* consent IP address;
* source URL;
* status;
* audit events.

The plugin integrates with WordPress' personal-data exporter and eraser when an email address is available. Contacts without email can be handled from the CRM administration screens.

The plugin also supplies suggested privacy-policy text through WordPress' privacy-policy helper.

IP capture uses `REMOTE_ADDR`. The plugin does not trust `HTTP_X_FORWARDED_FOR` by default because that header can be spoofed when proxy trust is not explicitly configured.

No plugin-owned telemetry is enabled, and the Community edition makes no mandatory external HTTP requests.

== Retention ==

The retention-days setting is a governance reference. Version 1.5.1 does not automatically delete records solely because that period has elapsed. Administrators should apply a retention policy appropriate to their context.

== Uninstall ==

Data is preserved by default.

If the administrator explicitly enables **delete data on uninstall**, uninstall.php removes the plugin tables and stored options. Public WordPress pages created by the setup wizard are not deleted automatically.

== Security ==

The plugin uses WordPress security primitives including capabilities, nonces, sanitization, escaping, prepared queries, ID validation, CSRF protection, honeypot protection, IP rate limiting and CSV Injection mitigation.

Please see `SECURITY.md` in the package for responsible disclosure guidance.

== Developer Hooks ==

Actions include:

* `wcc_contact_created`
* `wcc_contact_updated`
* `wcc_consent_event_recorded`

Filters include:

* `wcc_consent_text`
* `wcc_consent_version`
* `wcc_integration_providers`

The WCC-prefixed PHP API and database option/table prefixes are intentionally retained for backward compatibility with installations that used earlier development builds.

== External services ==

The Community edition does not require or call an external service to provide its core features. It contains no real WhatsApp API tokens and no fabricated API endpoints.

Future messaging integrations should be distributed separately and use official provider APIs and terms.

== Trademark notice ==

WhatsApp is a trademark of Meta Platforms, Inc. OptinBridge CRM – Consent & Contact Manager is an independent project and is not affiliated with, endorsed by or sponsored by Meta Platforms, Inc. or WhatsApp.

== Frequently Asked Questions ==

= Does it extract members from WhatsApp groups? =

No. The plugin does not access groups or collect their participants.

= Does it automatically send WhatsApp messages? =

No. The Community edition does not send messages automatically.

= Can a blocked number sign up again? =

Not while it remains blocked. A public attempt is rejected and can be audited. An administrator may unblock the record to `pending`; a fresh explicit opt-in is then required before the contact becomes `authorized` again.

= Does the plugin guarantee LGPD/GDPR compliance? =

No. It provides technical tools for consent records, privacy workflows and data minimization, but legal compliance depends on the site's policies, purposes, legal bases, notices and actual use of the data.

= Does it send my CRM data to the plugin author? =

No. There is no plugin-owned telemetry or mandatory external data transmission in the Community edition.

== Upgrade Notice ==

= 1.5.1 =
Public-release hardening, independent branding, improved documentation and compatibility checks. Existing WCC database tables/options and shortcodes are preserved.

== Changelog ==

= 1.5.1 =
* Public-release preparation release.
* Revalidated WordPress 7.1 compatibility metadata and public documentation.
* No database schema changes and no intentional behavioral changes from the approved 1.5.0 baseline.

= 1.5.0 =
* Public release candidate branded as OptinBridge CRM – Consent & Contact Manager.
* Added activation requirements check for WordPress 6.4+ and PHP 8.0+.
* Refreshed WordPress.org-style readme and privacy disclosures.
* Preserved WCC database/options/API and shortcodes for upgrade compatibility.
* Updated translation template and release documentation.
* Added trademark and migration notes.

= 1.4.0 =
* Added setup wizard and readiness indicator.
* Added diagnostics and setup-page validation.

= 1.3.1 =
* Fixed campaign CSV export callback.

= 1.3.0 =
* Added campaign audience preview and campaign CSV export.

= 1.2.0 =
* Added professional dashboard, tags, saved campaigns and diagnostics.

= 1.1.1 =
* Blocked contacts can no longer bypass the administrative block through public registration.

= 1.1.0 =
* Added Consent Passport, REST API, Gutenberg block and developer extension points.
