=== HelpWP ===
Contributors: easysuite, easycommerce
Tags: knowledge base, documentation, helpdesk, support, tickets, chatbot, ai, auto responder, rag
Requires at least: 6.0
Tested up to: 6.9
Requires PHP: 7.4
Stable tag: 0.1
License: GPLv3
License URI: https://www.gnu.org/licenses/gpl-3.0.html

Docs, tickets, AI chatbot, and AI auto-responder for WordPress. One plugin, one admin menu, one settings option.

== Description ==

**HelpWP** is an all-in-one help desk for WordPress. A public knowledge base, a client-facing ticket system, an embeddable AI chatbot, and a ticket auto responder, all in a single plugin under one "HelpWP" admin menu and one settings option.

The base help-desk features (docs, tickets, emails, migration) work fully offline. The optional AI features (chatbot, auto responder, doc sync) connect to the HelpWP RAG service and require a one-time site registration.

= Modules =

* **Docs** - public knowledge base (custom post type `helpwp_doc`).
* **Tickets** - client support queue (custom post type `helpwp_ticket`).
* **AI Chatbot** - embeddable JavaScript widget that answers visitor questions from your synced docs.
* **AI Auto Responder** - replies to tickets on a delay using the same knowledge base.
* **Migration** - one-click import from **BetterDocs**, **weDocs**, **Echo Knowledge Base**, **BasePress**, **Awesome Support**, **SupportCandy**, and **JS Help Desk**.

Either Docs or Tickets can be turned off under **HelpWP > Settings > General > Modules**. At least one must remain active.

= Docs =

* Hierarchical **Topics** (`helpwp_topic`) and shared **Products** (`helpwp_product`) taxonomies.
* Configurable URL structure: plain, topic-based, product-based, or nested. Selectable under **Settings > Docs > Permalink**.
* `[helpwp_docs]` shortcode renders a grouped, searchable archive.
* Upvote and downvote buttons on every doc.
* Fancybox image zoom and Prism.js syntax highlighting in the single-doc template.
* Doc list caching via WP object cache (Redis/Memcached) or transients, with a configurable TTL. Automatically invalidated on every doc save or delete. Toggle and lifetime under **Settings > Docs > Cache**.

= Tickets =

* Eight custom statuses: Open, In Progress, Waiting, On Hold, Resolved, Reopened, Cancelled, Closed.
* Automatic status transitions: agent reply -> In Progress, client reply -> Waiting. Configurable; can be disabled per-ticket via filter or globally in Settings. Skipped when the ticket is resolved, closed, or cancelled.
* Three custom roles: `helpwp_manager`, `helpwp_agent`, `helpwp_user`.
* `[helpwp_tickets]` shortcode shows the client's ticket list with filters and pagination.
* `[helpwp_new_ticket]` shortcode renders the submission form.
* **Manageable form fields** - show/hide built-in fields, reorder them, mark any as required, and add unlimited custom fields (text, number, email, textarea, or select with admin-defined options) under Settings > Tickets > Form Fields.
* **Agent assignment** - three strategies: random (default), round-robin, or least-loaded. Set a per-agent maximum open-ticket limit. Auto-assignment can be disabled for manual-only workflows.
* **Agents management page** (HelpWP > Agents) - lists all Agent-role users with their current open ticket count, total assigned, and an at-capacity badge.
* Email-based "helpwplogin" - the client receives a short-lived signed URL (5-minute transient) and is signed in on click; no traditional password is required.
* Optional guest ticket submission - let unauthenticated visitors submit tickets (name and email collected on the form).
* Reasons taxonomy (`helpwp_reason`) and four urgency levels (Low, Medium, High, Severe).
* Notification emails on new ticket (to client and to agent), agent reply, client reply, and ticket resolved, plus the login verification code email. Each one has a configurable Header, Subject, and Body.
* Placeholders supported in all email fields: `##site_name##`, `##client_name##`, `##agent_name##`, `##ticket_id##`, `##ticket_subject##`, `##ticket_link##`, `##ticket_product##`, `##ticket_priority##`, `##code##`.
* Full REST API under `/wp-json/helpwp/v1/`.

= AI Chatbot =

A vanilla-JS chat widget you embed with a single `<script>` tag. Generated from **Settings > AI > Configure** once your site is registered.

* Branding: agent name, avatar, primary color, launcher position (bottom-left or bottom-right), launcher tooltip, and panel width / height.
* Conversation copy: custom welcome message, input placeholder, and clickable "suggested prompt" chips that disappear after the first user message.
* Auto-open triggers: open the panel automatically after a delay (seconds), at a scroll percentage, or on exit-intent. Fires at most once per browsing session.
* URL targeting: `data-show-on` and `data-hide-on` accept comma-separated path patterns with `*` wildcards (e.g. `/docs/*`, `/checkout/*`). Path-only matching, query strings ignored. Hide rules win.
* Business hours: define windows like `mon-fri:9-17, sat:10-14` in the visitor's local time. Outside hours, swap in an offline greeting or hide the launcher entirely.
* Conversation history persisted per-browser in `sessionStorage`.
* **Preview** button renders the widget in-place using the current settings (no save needed).
* **View Code** copies the embed snippet for any site, WordPress or not.
* **Download Plugin** packages the embed code into a tiny installable WordPress plugin you can hand to a customer.

= AI Auto Responder =

* Runs on WP-Cron. Each new ticket and each fresh client reply schedules a single bot-reply job after a configurable delay (minutes, hours, or days).
* The delay restarts every time the client posts again, so the bot only replies if a human agent has not.
* The reply is only posted when the RAG model's relevance score clears a configurable threshold (0-100%). Below that, the ticket stays for a human.
* Any agent reply, or any move to Resolved / Closed / Cancelled, cancels the pending bot job before it fires.
* The bot reply is posted as a ticket comment by a configurable author name (e.g. "Support Bot") and can optionally flip the ticket status to In Progress.
* Context sent to the AI: ticket title, client name, email, order meta, product terms, urgency, and the full client/agent transcript. The latest client message is the question.

= Migration =

One-click import from existing help-desk plugins, runs in batches in the background and is safe to re-run.

* **BetterDocs** - articles + `doc_category` -> HelpWP docs and topics.
* **weDocs** - container pages become topics; leaf pages become docs.
* **Echo Knowledge Base** - articles and categories from every KB (multi-KB supported).
* **BasePress** - articles + `knowledgebase_cat` -> HelpWP docs and topics.
* **Awesome Support** - tickets, replies, attachments, and product / department terms -> HelpWP tickets.
* **SupportCandy** - tickets, threads, customers, agent assignments, categories, priorities, tags, custom fields, and attachments -> HelpWP tickets and comments.
* **JS Help Desk** (js-support-ticket) - tickets, replies, departments, products, priorities, custom fields, and attachments -> HelpWP tickets, comments, reasons, and products.

A "Clean" action removes HelpWP content created by a previous migration of that source. The source plugin's data is never modified for the doc importers; for the custom-table ticket sources (SupportCandy, JS Help Desk) the Clean action also drops the imported source rows so the migration can be re-run from scratch.

= Settings, REST, hooks =

* All settings live in a single `helpwp_settings` option, keyed `[tab][section][field]`.
* Built on the native WordPress Settings API, extended with a repeater field type for multi-row configuration (used by Form Fields).
* Filterable schema via the `helpwp_settings_menus` filter.
* REST namespace: `helpwp/v1` (docs, tickets, comments, login, taxonomies, urgencies, AI register / verify / sync).
* Action hooks fire on the `helpwp-tickets-*` prefix (e.g. `helpwp-tickets-ticket_created`, `helpwp-tickets-client_commented`, `helpwp-tickets-ticket_status_changed`).
* `helpwp_ticket_form_fields()` returns the active form field registry; `helpwp_ticket_form_fields_default()` returns the factory defaults.
* Translation-ready (text domain `helpwp`, `.pot` template in `languages/`).

== Installation ==

1. Upload the `helpwp` folder to `/wp-content/plugins/`, or install the ZIP from **Plugins > Add New > Upload Plugin**.
2. Activate **HelpWP**.

On activation, HelpWP creates three pages and selects them in settings automatically:

* **Docs** -> hosts `[helpwp_docs]` (selected as Settings > Docs > Pages > Docs archive page).
* **My Tickets** -> hosts `[helpwp_tickets]` (selected as Settings > Tickets > Pages > My Tickets).
* **Submit a Ticket** -> hosts `[helpwp_new_ticket]` (selected as Settings > Tickets > Pages > New Ticket).

If a setting already points at a live page, or a page already exists whose content contains the matching shortcode, it is reused instead of duplicated. Re-activating never produces duplicate pages.

= After activation =

1. Add the auto-created pages to your theme menu under **Appearance > Menus**.
2. (Optional) Adjust the docs URL structure under **HelpWP > Settings > Docs > Permalink**. The selected docs archive page's slug becomes the docs base URL.
3. (Optional) Configure email branding (logo, footer) and notification copy under **HelpWP > Settings > Emails**.
4. (Optional, AI features) Open **HelpWP > Settings > AI > Configure**, enter your name and email, click **Register**, then paste the key emailed to you and click **Verify**.
5. (AI) Click **Sync Docs** in the AI Connectivity card to send your docs to the RAG service.
6. (AI) In the **Chatbot** section, configure the agent name, avatar, color, position, and any advanced options, then click **View Code** or **Download Plugin** to embed the widget. Use **Preview** to try the current settings without saving.
7. (AI) In the **Auto Responder** section, enable the bot, set the delay (minutes / hours / days), the relevance threshold, and the comment author name.

= Migrating from another plugin =

1. Make sure the source plugin (BetterDocs, weDocs, Echo KB, BasePress, Awesome Support, SupportCandy, or JS Help Desk) is still activated.
2. Open **HelpWP > Settings > Migration**.
3. Click **Migrate** next to the source. Progress is shown in the "Current migration" panel.
4. Re-run is safe; the migration is idempotent. **Clean** removes HelpWP content created from a previous migration of that source.

== Frequently Asked Questions ==

= Can I use only Docs or only Tickets? =

Yes. Untick the module you do not need under **Settings > General > Modules**. At least one must remain active.

= Do the AI features require a third-party service? =

Yes. The chatbot, auto responder, and doc sync connect to the HelpWP RAG service and need a free, one-time site registration. The base help-desk features (docs, tickets, emails, migration) work fully offline.

= How do clients log in to see their tickets? =

Through an email-based "helpwplogin" flow. The client requests a code, receives a short-lived signed link by email (5 minute transient), and is signed in automatically on click. No traditional password is required.

= Will the auto responder spam my tickets? =

No. It schedules at most one reply per client message, the delay restarts on every new client message, any human agent reply cancels the pending bot job, and the reply is only posted when the RAG relevance score clears your threshold.

= Can I embed the chatbot on a non-WordPress site? =

Yes. The widget is a single `<script>` tag with `data-*` attributes, hosted at ai.easysuite.org. Use **View Code** in the AI settings to copy the snippet, or **Download Plugin** to get a ready-made WordPress plugin for a customer site.

= Where are the settings stored? =

In a single `helpwp_settings` option, keyed by `[tab][section][field]`. Built on the native WordPress Settings API.

= Is there a REST API? =

Yes - `/wp-json/helpwp/v1/`. Endpoints cover docs, tickets, comments, login, taxonomies, urgencies, and the AI register / verify / sync flow.

= Can I translate it? =

Yes. Text domain is `helpwp`, the `.pot` template is at `languages/helpwp.pot`. Place `helpwp-{locale}.po` and `.mo` in `languages/`.

= Do I need an OpenAI / Anthropic API key? =

No. AI requests are proxied through the HelpWP RAG service and authenticated by your `site_key`. You do not configure any third-party model keys in WordPress.

= Where can I see what the AI has answered? =

Under **HelpWP > AI**, two extra tabs - **Chatbot Logs** and **Auto Responder Logs** - render paginated history fetched from the RAG service using your site key. Auto Responder Logs link back to the originating ticket.

= How do I disconnect a site from the AI service? =

In **HelpWP > AI > Configure**, the AI Connectivity card shows a **Disconnect** button next to the Connected badge once verified. It clears the stored credentials on this site; you can re-register at any time.

= Can I show the chatbot only on specific pages? =

Yes. The chatbot embed accepts `data-show-on` and `data-hide-on`, both comma-separated path patterns with `*` wildcards. Patterns are matched against the URL path only; query strings are ignored. Hide rules win when a page matches both lists.

= What happens to my data if I disable Docs or Tickets? =

Nothing is deleted. Disabling a module in **Settings > General > Modules** hides its admin sub-menus, settings tabs, and shortcode output, but the existing posts stay in the database. Re-enabling restores everything.

= Does the ticket editor use the block editor (Gutenberg)? =

No. Tickets force the Classic Editor with a custom meta box for ticket-specific fields (status, agent, urgency, reasons, product, order). Docs use the editor your site is otherwise configured for.

= Can I assign a ticket to a specific agent? =

Yes. The ticket edit screen has an Agent dropdown listing all users with the `helpwp_agent` role. New tickets are auto-assigned according to the strategy set under **Settings > Tickets > Assignment**: random (default), round-robin, or least-loaded. You can also disable auto-assignment entirely for manual-only workflows.

= Can I control how new tickets are assigned to agents? =

Yes. Under **HelpWP > Settings > Tickets > Assignment** you can choose between random, round-robin (rotate in order), and least-loaded (agent with fewest open tickets) strategies, plus set a per-agent maximum open-ticket limit. Agents at the limit are skipped during auto-assignment.

= Can I manage what fields appear on the ticket submission form? =

Yes. Under **HelpWP > Settings > Tickets > Form Fields** you can show or hide each built-in field, reorder them with up/down arrows, mark any as required, and add custom fields (text, number, email, textarea, or select with your own options). Custom field values are stored as post meta.

= Can I customize the notification email templates? =

Yes. Under **HelpWP > Settings > Emails**, every notification (login code, new ticket to client / agent, agent reply, client reply, ticket resolved) has its own Header, Subject, and Body fields with placeholder support. There is also a global email logo and footer text.

= How can I extend HelpWP? =

Through standard WordPress hooks. The `helpwp-tickets-*` action prefix exposes ticket lifecycle events (`ticket_created`, `client_commented`, `agent_commented`, `ticket_status_changed`). The `helpwp_settings_menus` filter lets you add settings tabs, sections, or fields. The `helpwp_auto_status_transition_on_comment` filter lets you opt out of automatic status flips on a per-comment basis. PSR-4 autoload is wired in `composer.json`.

== External Services ==

HelpWP's core features (docs, tickets, emails, migration) work entirely offline. The optional AI features connect to the **HelpWP RAG service** hosted at `https://helpwp.dev`.

**What the service is:** A retrieval-augmented generation (RAG) API that powers the AI chatbot and auto responder by searching your synced documentation and generating replies.

**When data is sent:**

* **Site registration** – when you click "Connect" in HelpWP > AI, your site URL, site title, your name, and email are sent to `https://helpwp.dev/wp-json/helpwp-rag/v1/sites` to create an account and receive a `site_key`.
* **Doc sync** – when you click "Sync Docs", your published documentation content is sent to `https://helpwp.dev/wp-json/helpwp-rag/v1/sync` so it can be indexed for AI queries.
* **Chatbot queries** – each visitor message sent to the chatbot is forwarded to `https://helpwp.dev/wp-json/helpwp-rag/v1/ask` along with your `site_key`.
* **Auto responder** – when a new ticket arrives, the ticket title, client name, email, order reference, product terms, urgency, and the client/agent conversation transcript are sent to `https://helpwp.dev/wp-json/helpwp-rag/v1/respond` to generate a suggested reply.
* **Usage & logs** – the plugin periodically fetches usage statistics and log entries from `https://helpwp.dev/wp-json/helpwp-rag/v1/usage` and `https://helpwp.dev/wp-json/helpwp-rag/v1/logs` using your `site_key`.
* **Disconnection** – when you click "Disconnect", your `site_key` is sent to `https://helpwp.dev/wp-json/helpwp-rag/v1/unverify` to deregister the site.

No data is sent to the HelpWP RAG service unless you explicitly enable the AI features and register your site.

* [HelpWP Terms of Service](https://helpwp.dev/terms/)
* [HelpWP Privacy Policy](https://helpwp.dev/privacy/)

== Screenshots ==

1. The unified HelpWP admin menu grouping Docs, Tickets, and shared taxonomies.
2. Docs archive rendered by the `[helpwp_docs]` shortcode.
3. Ticket list with filter bar, status badges, and pagination.
4. Single ticket view with comment thread and quick-edit modal for agents.
5. Settings > AI > Configure: register a site, sync docs, configure the chatbot and auto responder.
6. AI chatbot floating widget with configurable agent, avatar, color, position, suggested prompts, business hours, and URL targeting.
7. Settings > Migration tab listing supported source plugins.

== Changelog ==

= 0.1 =
* Initial release.

== Upgrade Notice ==

= 0.1 =
First public release.
