=== Sappien Connector ===
Contributors: cardeetech, neriomolina
Tags: chat, ai, chatbot, floating-widget, sappien
Requires at least: 5.9
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 2.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Connect a Sappien AI chat agent to your WordPress site. Supports floating widget, shortcode embedding, and HMAC-signed user identity.

== Description ==

**Sappien Connector** lets you embed a Sappien AI agent into any WordPress site with no custom code.

### Features

* **Floating widget** — A fixed button in the corner opens the chat when clicked.
* **Shortcode** — Use `[sappien_chat]` in any page, post, or block.
* **HMAC authentication** — Logged-in WordPress users are automatically identified via HMAC-SHA256 (secret key stays server-side, never in the browser).
* **Multiple agents** — The shortcode supports per-instance `key` and `secret` attributes.
* **Selective visibility** — Show the widget to everyone, logged-in users only, or logged-out visitors only.
* **Page exclusions** — Hide the floating widget on specific pages by slug.
* **Fully customizable** — Configure position, button color, icon, height, and width.

### Requirements

* An active and configured **Sappien** instance
* API Key (and optionally Secret Key) from your Sappien agent
* The URL of your Sappien server

Documents and agent instructions are managed from your Sappien admin panel.

### External API

This plugin connects exclusively to the Sappien server URL that you configure in Settings. No data is sent to Cardee Technologies or any other third party. See the Privacy Policy section below for details.

== Installation ==

1. Download the plugin from the WordPress Plugin Directory.
2. Upload the `sappien-connector` folder to `/wp-content/plugins/`.
3. Activate the plugin from the **Plugins** screen in WordPress.
4. Go to **Sappien** in the admin menu (or **Settings > Sappien Connector**) and enter your Server URL and API Key.

Alternatively, search for "Sappien Connector" directly in **Plugins > Add New** and click **Install Now**.

== Frequently Asked Questions ==

= Do I need a Sappien account? =

Yes. You need an active Sappien instance with an API Key. Contact your Sappien provider for credentials.

= Is the Secret Key secure? =

Yes. The Secret Key is used on the server to sign the user identity payload (HMAC-SHA256). It is never exposed to the browser or included in any frontend output.

= Can I use multiple agents on the same site? =

Yes. Use the shortcode with per-instance credentials: `[sappien_chat key="ck_agent2" secret="sk_secret2"]`

= Where do I upload documents or edit the agent instructions? =

In your Sappien admin panel. Since version 2.0.0 the plugin only connects the chat to your site; the agent's knowledge base and instructions are managed in Sappien.

= How do I know the plugin is connected to my Sappien server? =

Go to **Sappien** in the admin menu and press **Check connection**. The plugin loads your chat from the server with your API Key and shows "Connected" in green, or the reason it failed (wrong address, API Key not accepted, certificate or network error).

= How do I hide the widget on certain pages? =

In the **Configuration** tab, enter comma-separated page slugs in the **Exclude pages** field (e.g. `checkout, cart, my-account`).

= How does automatic user identification work? =

With a Secret Key configured, logged-in WordPress users are identified in the chat automatically. Their user ID, display name, and email are signed with HMAC-SHA256 and sent to Sappien so the agent can greet them by name.

= What happens when I update from a previous version? =

Settings are migrated automatically. No data is lost.

== Screenshots ==

1. Settings — connection, display mode, widget appearance, and visibility.

== Changelog ==

= 2.0.0 =
* Change: the Documents and Instructions tabs have been removed. Manage the agent's documents and instructions from your Sappien admin panel. The plugin now focuses on showing the chat on your site.
* New: a "Check connection" button in the settings. It really contacts your Sappien server and tells you whether the chat is reachable, whether the API Key is accepted, or what went wrong. "Connected" is no longer shown just because the fields are filled in.
* Compatibility: tested with WordPress 7.1.
* Fix: the widget CSS and JS are no longer loaded on pages listed in "Exclude pages", and excluded slugs are matched case-insensitively.
* i18n: completed the Spanish (es_ES) translation.
* Branding: the company name is now written "Cardee Technologies, SL.".

= 1.5.1 =
* Security: the document upload handler now verifies `is_uploaded_file()` before reading the temporary file.
* Security: uploaded files are validated against an allowlist of extensions (PDF, DOCX, TXT, MD) and the MIME type is derived from the validated extension instead of the browser-reported value.
* Fix: upload failures reported by PHP (size limits, partial uploads) are now detected and reported instead of being silently processed.
* Fix: a non-JSON response during upload (for example a web-server size limit) left the user with no feedback at all; errors are now always shown.
* Fix: the widget CSS and JS are no longer loaded on pages listed in "Exclude pages".
* Fix: excluded page slugs are matched case-insensitively.
* Fix: added the missing error handler when loading agent instructions.
* i18n: completed the Spanish (es_ES) translation, including strings introduced in 1.5.0 that were left untranslated, and corrected several wrong translations.
* Maintenance: removed unused `agent_name` and `agent_avatar_url` options left over from the previous splash screen.
* Maintenance: development dependencies are now excluded from the distributed package.

= 1.5.0 =
* UI: Sappien chat now loads directly when the widget opens — no intermediate screen, seamless experience.
* UI: smooth fade-in transition when the chat iframe finishes loading.
* UI: new `chat_bg_color` setting — background color of the widget panel visible while the chat loads.
* Shortcode: new `bg` attribute to override background color per instance.
* Shortcode: new `shadow` and `border` attributes (`yes`/`no`) to control shadow and border per embed.
* Admin: connection status indicator on the configuration page.
* Admin: visual refresh — CSS variables, cleaner cards, improved form layout.
* Compatibility: tested up to WordPress 7.0.

= 1.4.0 =
* Architecture: refactored monolithic plugin into modular class-based structure (`Sappien_Connector_Core`, `Sappien_Connector_Admin`, `Sappien_Connector_Settings`, `Sappien_Connector_Api`, `Sappien_Connector_Widget`).
* Security: replaced `phpcs:ignore` on SVG output with `wp_kses()` using an SVG allowlist (M1).
* Security: validated `$_GET['tab']` against an explicit allowlist before use (M2).
* Security: validated `user_email` with `is_email()` before including in HMAC payload (B3).
* Admin: replaced emoji characters in UI with inline SVG icons (B4).
* Admin: added `error_log()` call before every `wp_send_json_error()` in AJAX handlers (B5).
* Admin: full UI redesign — SaaS-style dashboard with header, card layout, styled tabs, toast notifications, and accessible drag-and-drop upload zone.
* i18n: English as source language; all previously Spanish strings rewritten to English; Spanish (`es_ES`) translation added.
* WordPress.org: added `LICENSE` file; updated `readme.txt` to English with full FAQ and changelog.

= 1.3.0 =
* Improved option migration from previous version.
* Better error handling in file validation.
* Improved admin interface with Sappien branding.
* New admin menu system.
* Improved WordPress.org compatibility.

= 1.2.0 =
* Rebranding: now "Sappien Connector" by Cardee Technologies, SL.
* Full WordPress.org compliance.
* Separated CSS/JS into external files.
* Complete internationalization.
* Security improvements: capability checks in AJAX handlers.
* Server-side file size validation.

= 1.1.0 =
* Initial release as "Sappien Chat".

== Upgrade Notice ==

= 2.0.0 =
Documents and instructions are now managed in your Sappien admin panel: the plugin's Documents and Instructions tabs are removed. The chat, shortcode and all settings keep working.

= 1.5.1 =
Recommended update. Hardens document upload validation, fixes uploads failing without an error message, stops the widget assets from loading on excluded pages, and completes the Spanish translation. No action required — settings are preserved.

= 1.5.0 =
The chat now opens directly with no intermediate screen, plus a customizable panel background color. Compatible with WordPress 7.0. No action required — settings are preserved.

= 1.4.0 =
Modular architecture refactor and full UI redesign. Settings are migrated automatically. No action required.

== Privacy Policy ==

This plugin connects to the Sappien server URL that the site administrator configures in the plugin settings.

**Data transmitted to the configured Sappien server:**

* For logged-in users (when Secret Key is set): user ID, display name, email address, and HMAC-SHA256 signature.
* Chat messages entered by site visitors.

**This plugin does not transmit any data to Cardee Technologies or any server other than the Sappien instance you configure.**

For privacy details specific to your Sappien instance, consult your Sappien provider.
