=== OptinBridge CRM – Consent & Contact Manager ===
Contributors: justocrivelaro
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.6
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 ==

`[optinbridge_consent_form]`

Displays the public registration form.

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

Displays the registration form tied to one active group.

`[optinbridge_unsubscribe_form]`

Displays the public unsubscribe form.

`[optinbridge_support_form]`

Displays the native public support/feedback form. Configure the destination e-mail in **OptinBridge CRM > Configurações**.



== 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/optinbridge-crm/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.5 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:

* `optinbridge_contact_created`
* `optinbridge_contact_updated`
* `optinbridge_consent_event_recorded`

Filters include:

* `optinbridge_consent_text`
* `optinbridge_consent_version`
* `optinbridge_integration_providers`

Version 1.5.5 uses the OptinBridge-prefixed PHP API, options and database tables. A one-time migration preserves data created by earlier development builds. The public API, REST namespace and shortcodes use the OptinBridge-specific prefix to avoid naming collisions.

== 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.6 =
Uses WordPress identifier placeholders for atomic rate-limit queries and documents intentional cache bypasses.

= 1.5.5 =
Security and WordPress.org review hardening: prefixed public identifiers, readable JavaScript sources, and atomic public rate limiting.

== Changelog ==

= 1.5.6 =
* Reworked atomic rate-limit SQL to use WordPress `%i` identifier placeholders and `%s` value placeholders.
* Documented intentional direct, uncached database access required for concurrency-safe throttling.
* Removed dynamic SQL interpolation from the rate-limit read/write queries.

= 1.5.5 =
* Replaced generic public shortcodes with `[optinbridge_consent_form]` and `[optinbridge_unsubscribe_form]`.
* Changed the REST namespace to `/wp-json/optinbridge-crm/v1/` to avoid naming collisions.
* Replaced transient get-then-set throttles with atomic counters backed by a plugin-owned database table.
* Added the rate-limit table to activation/upgrade and explicit full-uninstall cleanup.
* Expanded the custom admin and public JavaScript into human-readable source files included in the plugin package.
* Re-audited state-changing administrative handlers for capability and nonce verification.

= 1.5.3 =
* Added public release version/ZIP settings and live counter to the admin settings page.

= 1.5.2 =
* Added native public support/feedback form shortcode: `[optinbridge_support_form]`.
* Added nonce, honeypot and per-IP rate limiting for support submissions.
* Added configurable support destination e-mail and hourly limit.
* Added optional attachment support (JPG, PNG, WebP, PDF, TXT; max 2 MB).
* Support submissions use `wp_mail()` and are not stored as tickets in the database.
* Audit logs record only request type/version outcome, not submitted message or e-mail.
* Added explicit privacy consent and privacy-policy link.

= 1.5.1 =
* Public distribution release candidate based on the approved 1.5.0 stable baseline.
* Revalidated package metadata and WordPress.org-facing documentation.
* Confirmed GPLv2-or-later declaration, privacy disclosures, uninstall behavior, and no mandatory telemetry/external services.

= 1.5.0 =
* Hardened public unsubscribe against phone-number enumeration.
* Added honeypot and per-IP/phone throttling to unsubscribe.
* Fixed public post-submit/source URL normalization for Elementor template previews.
* Unified Settings capability with the configured CRM management capability.
