=== NiroHelp ===
Contributors: easysuite
Tags: knowledge base, documentation, helpdesk, support, tickets
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 0.8.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 ==

**NiroHelp** 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 "NiroHelp" 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 NiroHelp RAG service and require a one-time site registration.

= Modules =

* **Docs** - public knowledge base (custom post type `nirohelp_doc`).
* **Tickets** - client support queue (custom post type `nirohelp_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 **NiroHelp > Settings > General > Modules**. At least one must remain active.

= Docs =

* Hierarchical **Topics** (`nirohelp_topic`) and shared **Products** (`nirohelp_product`) taxonomies.
* Configurable URL structure: plain, topic-based, product-based, or nested. Selectable under **Settings > Docs > Permalink**.
* `[nirohelp_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.
* **Display settings** (Settings > Docs > Display) — toggles for sidebar, breadcrumbs, prev/next pagination, rating buttons, and comments. Configurable docs per page and topic card limits.
* Reader comments on doc pages (toggle under Settings > Docs > Display).
* 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 globally under **Settings > Tickets > Behaviour** or per-ticket via `nirohelp_auto_status_transition_on_comment` filter. Skipped when the ticket is resolved, closed, or cancelled.
* Three custom roles: `nirohelp_manager`, `nirohelp_agent`, `nirohelp_user`.
* `[nirohelp_tickets]` shortcode shows the client's ticket list with filters and pagination.
* `[nirohelp_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** (NiroHelp > Agents) - lists all Agent-role users with their current open ticket count, total assigned, and an at-capacity badge.
* Three configurable client login methods under **Settings > Tickets > Submission > Login method**: (1) Verification code — client enters email, receives a 6-digit OTP, enters it to log in; (2) Magic link — client enters email, receives a one-click login link in their inbox; (3) Password — standard login form with a two-step sign-up flow (email verified via OTP before account is created).
* Optional guest ticket submission - let unauthenticated visitors submit tickets (name and email collected on the form).
* Reasons taxonomy (`nirohelp_reason`) and four urgency levels (Low, Medium, High, Severe).
* Notification emails on new ticket (to client and to agent), agent reply, client reply, ticket resolved, login verification code, and magic link login. Each one has a configurable Header, Subject, and Body.
* Email branding under **Settings > Emails > Branding** — upload logo and set footer text applied to all ticket emails.
* Placeholders supported in all email fields: `##site_name##`, `##client_name##`, `##agent_name##`, `##ticket_id##`, `##ticket_subject##`, `##ticket_link##`, `##ticket_product##`, `##ticket_priority##`, `##code##` (OTP emails), `##link##` (magic link email).
* Full REST API under `/wp-json/nirohelp/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` -> NiroHelp 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` -> NiroHelp docs and topics.
* **Awesome Support** - tickets, replies, attachments, and product / department terms -> NiroHelp tickets.
* **SupportCandy** - tickets, threads, customers, agent assignments, categories, priorities, tags, custom fields, and attachments -> NiroHelp tickets and comments.
* **JS Help Desk** (js-support-ticket) - tickets, replies, departments, products, priorities, custom fields, and attachments -> NiroHelp tickets, comments, reasons, and products.

A "Clean" action removes NiroHelp 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 `nirohelp_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 `nirohelp_settings_menus` filter.
* REST namespace: `nirohelp/v1` (docs, tickets, comments, login, wp-login, wp-signup, taxonomies, urgencies, AI register / verify / sync).
* Action hooks fire on the `nirohelp-tickets-*` prefix (e.g. `nirohelp-tickets-ticket_created`, `nirohelp-tickets-client_commented`, `nirohelp-tickets-ticket_status_changed`).
* `nirohelp_ticket_form_fields()` returns the active form field registry; `nirohelp_ticket_form_fields_default()` returns the factory defaults.
* Translation-ready (text domain `nirohelp`, `.pot` template in `languages/`).

== Installation ==

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

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

* **Docs** -> hosts `[nirohelp_docs]` (selected as Settings > Docs > Pages > Docs archive page).
* **My Tickets** -> hosts `[nirohelp_tickets]` (selected as Settings > Tickets > Pages > My Tickets).
* **Submit a Ticket** -> hosts `[nirohelp_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 **NiroHelp > 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 **NiroHelp > Settings > Emails**.
4. (Optional, AI features) Open **NiroHelp > 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 **NiroHelp > 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 NiroHelp 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 NiroHelp 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? =

Three methods, selectable under **Settings > Tickets > Submission > Login method**: (1) **Verification code** (default) — client enters email, receives a 6-digit OTP, enters it on the form and is signed in. (2) **Magic link** — client enters email and receives a one-click login link in their inbox; no code step. (3) **Password** — standard email + password login form with a sign-up option; new accounts require email verification via OTP before the account is created.

= 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 `nirohelp_settings` option, keyed by `[tab][section][field]`. Built on the native WordPress Settings API.

= Is there a REST API? =

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

= Can I translate it? =

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

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

No. AI requests are proxied through the NiroHelp 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 **NiroHelp > 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 **NiroHelp > 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 `nirohelp_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 **NiroHelp > 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 **NiroHelp > 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 **NiroHelp > 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 NiroHelp? =

Through standard WordPress hooks. Action hooks with the `nirohelp-tickets-*` prefix expose: `ticket_created`, `client_commented`, `agent_commented`, `agent_changed`, `ticket_status_changed`, `ticket_status_{new}_to_{old}` (specific transitions), `code_generated`, and `user_found`. Doc hooks: `nirohelp-doc_created`, `nirohelp-logged_in`, `nirohelp-after_doc_content`, `nirohelp_tickets_comment_added`, `nirohelp_user_inserted`, `nirohelp-tickets-ticket_model_status_changed`. Filters include `nirohelp_settings_menus` (customize settings schema), `nirohelp_product_post_types` (add CPTs to Products taxonomy), `nirohelp_auto_status_transition_on_comment` (per-comment status flips), and `nirohelp_cloud_site_url` (override RAG endpoint). PSR-4 autoload is wired in `composer.json`.

== External Services ==

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

**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 NiroHelp > AI, your site URL, site title, your name, and email are sent to `https://nirohelp.com/wp-json/nirohelp-cloud/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://nirohelp.com/wp-json/nirohelp-cloud/v1/sync` so it can be indexed for AI queries.
* **Chatbot queries** – each visitor message sent to the chatbot is forwarded to `https://nirohelp.com/wp-json/nirohelp-cloud/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://nirohelp.com/wp-json/nirohelp-cloud/v1/respond` to generate a suggested reply.
* **Usage & logs** – the plugin periodically fetches usage statistics and log entries from `https://nirohelp.com/wp-json/nirohelp-cloud/v1/usage` and `https://nirohelp.com/wp-json/nirohelp-cloud/v1/logs` using your `site_key`.
* **Disconnection** – when you click "Disconnect", your `site_key` is sent to `https://nirohelp.com/wp-json/nirohelp-cloud/v1/unverify` to deregister the site.

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

* [NiroHelp Terms of Service](https://nirohelp.com/terms/)
* [NiroHelp Privacy Policy](https://nirohelp.com/privacy/)

== Screenshots ==

1. The unified NiroHelp admin menu grouping Docs, Tickets, and shared taxonomies.
2. Docs archive rendered by the `[nirohelp_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.8.1 =
* Update assets

= 0.8 =
* Initial release.

== Upgrade Notice ==

= 0.8 =
First public release.
