=== Centous AI Search with Askiva ===

Contributors: centous
Donate link: https://centousplugins.com/
Requires at least: 5.8
Tested up to: 7.0
Stable tag: 1.0.0
Requires PHP: 7.4
License: GPL v2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Centous AI Search with Askiva connects WordPress to Askiva for semantic search, content sync, and streamed AI answers.

== Description ==

Centous AI Search with Askiva is developed by [Centous](https://centousplugins.com/). It is **not** affiliated with, endorsed by, or an official product of Askiva. It connects your WordPress site to [Askiva](https://askivasearch.com/), a third-party AI search platform, for indexing, semantic search, and streamed AI answers.

This plugin connects your WordPress site to the Askiva backend for:

* **Content indexing**: batch sync of published posts/pages to Askiva
* **AI search**: semantic search with streamed AI answers (GFM Markdown)
* **Rich results**: list or grid layout, thumbnails, pagination, “Read more” links
* **Query help**: “Did you mean” suggestions when the API detects typos
* **Admin tools**: connection settings, sync dashboard, statistics, logs

The frontend search box uses AJAX by default: results and the AI answer load inline without a full page reload. Server-rendered results are still supported when a search URL contains a query parameter.

== External services ==

This plugin connects to third-party Askiva services. An Askiva account is required. Centous does not operate these services.

=== Askiva account portal ===

Website: [https://askivasearch.com/](https://askivasearch.com/)

Used to register an account, add your WordPress site, and obtain your **Site Identifier** and **API Key**.

Data sent when you use the portal (in your browser, outside this plugin): account registration details and site information you enter when adding a site.

Terms of use: [https://askiva.io/legal/terms-of-use](https://askiva.io/legal/terms-of-use)
Privacy policy: [https://askiva.io/legal/privacy-policy](https://askiva.io/legal/privacy-policy)

=== Askiva API ===

API endpoint (default): `https://askiva-bk.postyoulike.com/api/v1`

Used to verify your connection, sync published WordPress content, run search queries, stream AI answers, and load dashboard statistics.

Data sent from your WordPress site to the API:

* **On connect (Verify Key):** Site Identifier and API Key
* **On sync:** published post/page title, URL, slug, excerpt, plain-text content, headings, categories, and tags
* **On search:** search query, Site Identifier, API Key, pagination, and optional content type filter
* **On dashboard stats:** Site Identifier and API Key

Data is sent only when you or a visitor triggers these actions (connect, sync, search, or when an administrator views the dashboard).

Terms of use: [https://askiva.io/legal/terms-of-use](https://askiva.io/legal/terms-of-use)
Privacy policy: [https://askiva.io/legal/privacy-policy](https://askiva.io/legal/privacy-policy)

== Installation ==

1. Upload the `centous-ai-search-with-askiva` folder to `/wp-content/plugins/`
2. Activate the plugin through **Plugins** in WordPress admin
3. Register on Askiva, add your site, and copy your credentials (see Configuration below)
4. Go to **Centous Search → Settings** in WordPress and connect your site
5. Run an initial sync from **Centous Search → Sync**
6. Add `[askiva_search]` to a page or post

== Configuration ==

=== Create your Askiva account and site ===

1. Register and log in at [Askiva](https://askiva-ai-frontend.vercel.app/)
2. In the dashboard sidebar, click **Sites**
3. On the Sites page, click **Add Site**
4. In the popup, enter your website details and click **Add Site**
5. Your site appears in the list: click it to open the site detail page
6. On the detail page, copy your **Site Identifier** and **API Key** (you will enter these in the WordPress plugin)

=== Connect your site ===

1. Open **Centous Search → Settings** in WordPress admin
2. Enter your **Site ID** (the **Site Identifier** from the Askiva portal, e.g. `my-site-aBc12XyZ`)
3. Enter your **Site Key** (the **API Key** from the Askiva portal)
4. Click **Verify Key**: the plugin calls `POST /wp/verify` to validate credentials
5. When connected, Site ID and Site Key fields are locked until you disconnect

Saved settings also include numeric `api_site_id` when the verify response returns one (used for search API compatibility).

=== Sync your content ===

After a successful connection:

1. Go to **Centous Search → Sync**
2. Click **Start Sync** to index your published WordPress content to Askiva
3. Wait for the sync to complete (monitor progress and logs on the Sync page)

When sync finishes, your site content is available for AI search.

=== Enable search on your site ===

Add the search shortcode to any page or post:
[askiva_search]


Visitors can search your site and see streamed AI answers with semantic results. See **Usage** below for shortcode options and layout settings.

=== Search & display settings ===

Under **Centous Search → Settings**:

| Setting | Description | Default |
|--------|-------------|---------|
| Content Items per Index Cycle | Posts/pages sent per sync batch | 10 |
| Results Display Mode | `list` or `grid` for search results | list |
| Results per Page | Results shown per page (1–100) | 10 |
| Thumbnail Size | Result thumbnail size in px (48–400) | 96 |

=== Advanced: API base URL (optional) ===

Note: Most users do not need this step. If you registered at [Askiva](https://askiva-ai-frontend.vercel.app/) and connect with your Site Identifier and API Key, the plugin uses its built-in API endpoint automatically.

Override the API base URL only when Askiva support directs you to a different host (for example a staging environment or a custom API deployment). The URL must include the `/api/v1` path.

Option 1: `wp-config.php` (recommended)

```php
define( 'ASKIVA_API_BASE', 'https://your-askiva-api.example.com/api/v1' );
```

Option 2: filter hook

```php
add_filter( 'askiva_api_base', function () {
    return 'https://your-askiva-api.example.com/api/v1';
} );
```

If neither is set, the plugin uses `https://askiva-bk.postyoulike.com/api/v1` by default.

== Usage ==

=== Search shortcode ===

```
[askiva_search]
```

Place on any page, post, or widget area. Visitors search inline; the AI answer streams in and results appear below the form.

Common setup:

1. Create a page (e.g. `/search/`) with `[askiva_search show_results="1"]`
2. For a header or sidebar button that redirects to your search page, use the popup shortcode:

```
[askiva_search_popup results_url="/search/" trigger_text="Search"]
```

3. Optionally set a global results URL for the popup shortcode:

```php
add_filter( 'askiva_search_results_url', function () {
    return site_url( '/search/' );
} );
```

Note: `[askiva_search show_results="0"]` hides pre-loaded results on page load, but search still runs inline on that page via JavaScript. Use the popup shortcode to redirect visitors to a separate search page.

Shortcode attributes:

| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| `placeholder` | string | Search… | Input placeholder |
| `button_text` | string | Search | Button label (legacy) |
| `site_id` | string | *(from settings)* | Override site ID; saved settings always win when set |
| `type` | string | *(empty)* | Optional content type filter sent to API |
| `results_url` | string | *(auto)* | Full URL or path for search results page |
| `results_page_id` | int | - | WordPress page ID for results (alternative to `results_url`) |
| `show_results` | `auto` \| `0` \| `1` | auto | When to show results block (`auto` = when `?q=` is present) |
| `results_limit` | int | *(from settings)* | Results per page (1–100) |
| `view_all_limit` | int | 50 | Max results when “view all” is used |
| `ajax` | `0` \| `1` | 0 | Legacy flag; JS still handles live search. Affects pagination scroll behavior |
| `live` | bool | false | Search while typing (debounced) |
| `min_chars` | int | 2 | Minimum characters before search runs |
| `debug` | `0` \| `1` | 0 | Pass debug flag to search API (admin troubleshooting) |
| `limit` | int | 10 | Legacy AJAX limit |

URL query parameters:

| Parameter | Default name | Purpose |
|-----------|--------------|---------|
| Search query | `q` | Search term (`askiva_q` legacy alias still supported) |
| Page | `askiva_page` | Pagination |
| View all | `view` | Use `view=all` for expanded result limit |

Change the query parameter name:

```php
add_filter( 'askiva_search_query_param', function () {
    return 'q';
} );
```

=== Popup search shortcode ===

Opens a modal search box and redirects to your results page on submit:

```
[askiva_search_popup results_url="/search/" trigger_text="Search"]
```

| Attribute | Default | Description |
|-----------|---------|-------------|
| `trigger_text` | Search | Button that opens the popup |
| `placeholder` | Search… | Input placeholder |
| `close_text` | Close | Close button label |
| `results_url` | *(auto)* | Where to send the user after search |
| `results_page_id` | - | Page ID alternative to `results_url` |
| `min_chars` | 2 | Minimum query length |

=== Frontend search behavior ===

When a visitor searches:

1. **AI answer**: streamed via Server-Sent Events (`/search/stream`), rendered as GFM Markdown (bold, italics, bullet/numbered lists) with DOMPurify sanitization
2. **Search results**: fetched via AJAX proxy (`/search/`), with thumbnails and excerpts
3. **Did you mean**: shown when the API returns a `did_you_mean` suggestion
4. **Source links**: `[Source N]` markers in the AI answer link to matching result URLs

Bundled assets (no external CDN): `marked.min.js` (v15.0.12), `purify.min.js`, `search.js`, `search.css`.

=== Theme template overrides ===

Copy templates into your theme to customize markup:

```
wp-content/themes/your-theme/centous-ai-search-with-askiva/
  search.php
  search-results.php
  search-result-item.php
  search-popup.php
```

== Dashboard ==

Centous Search → Dashboard shows (when connected):

* Connected site / domain
* Indexed pages
* Searches this month
* AI answers generated

Statistics are fetched from `GET /wp/stats` and cached for performance.

== Sync ==

Centous Search → Sync:

1. Optionally enable **Delete all data and start fresh sync** for a full re-index
2. Click **Start Sync** to index published content in batches
3. Monitor progress and logs in the sync panel

Sync uses `POST /wp/documents/` in batches sized by **Content Items per Index Cycle**. Long-running sync requests extend PHP time limits automatically.

Note: Closing the browser may pause progress; resume from the Sync page.

== WordPress REST API (plugin) ==

Registered under `askiva/v1` for remote/automated sync control:

| Route | Method | Description |
|-------|--------|-------------|
| `/wp-json/askiva/v1/remote-sync` | POST | Start or resume sync (returns immediately; use `/sync/tick` to advance) |
| `/wp-json/askiva/v1/sync/status` | GET | Current sync status |
| `/wp-json/askiva/v1/sync/start` | POST | Start sync (`fresh_start` optional) |
| `/wp-json/askiva/v1/sync/pause` | POST | Pause sync |
| `/wp-json/askiva/v1/sync/resume` | POST | Resume sync |
| `/wp-json/askiva/v1/sync/restart` | POST | Restart sync |
| `/wp-json/askiva/v1/sync/tick` | POST | Process one sync tick |

Authenticate with the same credentials saved in **Centous Search → Settings**:

* **Site identifier**: send as `site_id`, `site_identifier`, or `api_site_id` (JSON body or query), or header `X-Askiva-Site-Id` / `X-Askiva-Site-Identifier`
* **Site key**: send as `site_key` or `api_key` (JSON body or query), or header `X-Askiva-Key`

Both the string site identifier (e.g. `sdgicity-kH33Isf1`) and numeric `api_site_id` from verify are accepted when they match saved settings.

== Askiva backend API ==

All paths are relative to your configured API base (e.g. `https://api.example.com/api/v1`).

Connection and status

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/wp/verify` | Validate Site ID + Site Key |
| POST | `/wp/connect` | Legacy connect |
| GET | `/wp/status` | Connection test (`X-Askiva-Key` header) |
| GET | `/wp/stats` | Site statistics |

Documents and indexing

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/wp/documents/` | Index a batch of documents |
| GET | `/wp/documents/batch/{id}` | Batch status |
| DELETE | `/wp/documents/all` | Delete all indexed documents (`site_id` + `api_key` in JSON body, `X-Askiva-Key` header) |

Search (frontend)

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/search/` | Search results + AI answer metadata |
| POST | `/search/stream` | Streamed AI answer (SSE) |

Search requests send `site_id`, `api_key`, `query`, `limit`, and `page` in the JSON body, plus `X-Askiva-Key` header.

== Developer filters ==

```php
// API base URL
add_filter( 'askiva_api_base', $callback );

// Default search results page URL
add_filter( 'askiva_search_results_url', $callback );

// URL query parameter name (default: q)
add_filter( 'askiva_search_query_param', $callback );

// Include API trace/debug in search payload (default: true)
add_filter( 'askiva_search_include_trace', $callback );

// Template variables passed to PHP templates
add_filter( 'askiva_template_vars', $callback, 10, 2 );
```

== Requirements ==

* WordPress 5.8+
* PHP 7.4+
* Valid Askiva account (Site Identifier and API Key from the [Askiva dashboard](https://askiva-ai-frontend.vercel.app/))
* Outbound HTTPS to the Askiva API host
* Published content to index (drafts are skipped)

== Features ==

* Secure admin AJAX with nonces and `manage_options` checks
* Site ID + Site Key connection with verify endpoint
* Batch content sync with pause/resume/restart
* Real-time sync status and error logging
* Streaming AI answers with GFM Markdown rendering
* “Did you mean” typo suggestions from API
* List and grid result layouts with configurable thumbnails
* Search popup shortcode for header/navigation use
* Server-rendered and AJAX search modes
* Theme template overrides
* WordPress REST sync endpoints for automation
* Cached dashboard statistics
* First-run redirect to settings
* Clean uninstall support

== Troubleshooting ==

=== Connection issues ===

1. Confirm **Site ID** and **Site Key** match the **Site Identifier** and **API Key** on your Askiva site detail page
2. If you use a custom API host, verify `ASKIVA_API_BASE` (or the `askiva_api_base` filter) includes `/api/v1` and points to the correct server
3. Use **Test Connection** on the Settings page
4. Check **Centous Search → Logs** for API error details

=== Search issues ===

1. Ensure the site is connected and content has been synced
2. Confirm the shortcode page loads `search.js` (no JavaScript console errors)
3. In browser DevTools → Network, inspect `askiva_public_search` and `askiva_public_search_stream` AJAX calls
4. Enable shortcode `debug="1"` for API trace data when diagnosing “Did you mean”

=== Sync issues ===

1. Review sync logs and error tab on **Centous Search → Sync**
2. Only **published** content is indexed
3. Try a fresh sync if indexed data looks stale or corrupted
4. Increase **Content Items per Index Cycle** cautiously on slow hosts

== Frequently Asked Questions ==

= Does this work with all themes? =

Yes. The plugin ships self-contained CSS. Themes with aggressive list resets are handled via scoped styles for AI answer lists.

= Do I need an Askiva account? =

Yes. This plugin uses [Askiva](https://askivasearch.com/) as a third-party API service. Register at the [Askiva dashboard](https://askiva-ai-frontend.vercel.app/), add your site, and copy the **Site Identifier** and **API Key** into the plugin settings.

= Can I re-sync all content? =

Yes. Use **Start Sync** with “Delete all data and start fresh sync” on the Sync page, or the restart REST endpoint.

= Does search work without JavaScript? =

Partially. With `show_results="1"` and a query in the URL, PHP can render results server-side. The streaming AI answer requires JavaScript.

= Can I change the search URL parameter? =

Yes. Use the `askiva_search_query_param` filter (default: `q`).

== Screenshots ==

1. Centous AI Search with Askiva settings: connection and display options
2. Connected site confirmation
3. Sync dashboard with progress and logs
4. Frontend search with streaming AI answer and results
5. Grid layout search results

== Changelog ==

= 1.0.0 =

* Initial release as Centous AI Search with Askiva
* Site ID + Site Key connection via `/wp/verify`
* Content batch sync to Askiva (`/wp/documents/`)
* Search shortcode with inline AJAX results and streamed AI answers
* GFM Markdown AI answer rendering (marked v15.0.12 + DOMPurify, bundled locally)
* “Did you mean” suggestions from API `did_you_mean`
* `[Source N]` citation linkification in AI answers
* List/grid display modes and configurable thumbnails
* Search popup shortcode
* Dashboard statistics from `/wp/stats`
* WordPress REST sync control routes (`askiva/v1`)
* Admin sync logs, pause/resume/restart
* Theme template override support
* External services documentation for Askiva portal and API
* Plugin Check / WordPress coding standards compliance

== Upgrade Notice ==

= 1.0.0 =

Initial stable release of Centous AI Search with Askiva.

== Support ==

Plugin support: [Centous](https://centousplugins.com/), developer of this plugin.

Askiva (third-party service): account setup at [Askiva](https://askivasearch.com/) and [Askiva dashboard](https://askiva-ai-frontend.vercel.app/). Not affiliated with Centous.