# Peligent WP Plugin (WordPress AI Assistant)

## Overview
- Single-file PHP plugin: peligent-ai-assistant.php (~6100 lines)
- Current version: 1.7.17
- Requires WordPress 5.8+, WooCommerce, PHP 7.4+
- Tested up to WordPress 6.9
- Listed on WordPress.org plugin directory

## Structure
- peligent-ai-assistant.php — main plugin file (all logic, single-file architecture)
- assets/ — plugin icons, screenshots, CSS, JS for WordPress.org and admin
  - admin-settings.css / admin-settings.js — settings page styles/scripts
  - sidebar.css / sidebar-init.js — AI sidebar styles/initialization
  - peligent-ai-embed.js — embed script
  - peligent-rtl.css — RTL language support
- admin-ui/ — pre-built React app (Vite output), legacy admin UI
- readme.txt — WordPress.org listing, changelog, and metadata
- deploy-to-wordpress-svn.sh — SVN deployment script
- CLAUDE.md — this file

## Versioning
- **Both versions must always match**: `readme.txt` Stable tag and plugin header `Version:`
- Bump both when releasing. Use semantic versioning (major.minor.patch).
- Add a changelog entry in `readme.txt` under `== Changelog ==` for every version bump.

## Deploy to WordPress.org
SVN credentials are stored in `~/.netrc` (machine: plugins.svn.wordpress.org, login: peligent).

To deploy:
```bash
cd /home/sajad/workspace/peligent-wp-plugin
bash deploy-to-wordpress-svn.sh
```

The script:
1. Reads version from `readme.txt` Stable tag
2. Checks out WordPress SVN repo to /tmp/
3. Copies assets (icons, screenshots) to SVN assets/
4. Rsyncs plugin files to trunk/ (excludes .git, admin-ui, deploy script, wpai-embed.js)
5. Creates a version tag
6. Prompts for confirmation, then commits

**Note:** The script is interactive (has `read -p` prompts). For non-interactive deploy, run the SVN steps manually:
1. `svn checkout ... --depth immediates`
2. `svn update --set-depth infinity trunk` + `assets`
3. Copy assets + rsync plugin files to trunk
4. `svn copy trunk tags/{VERSION}` + `svn add --force`
5. `svn commit -m '...' --username peligent --password '...'` (password from ~/.netrc)
6. Clean up `/tmp/peligent-ai-assistant-svn`

## Architecture
- Single PHP class: `Peligent_For_WooCommerce_Plugin`
- Communicates with app.peligent.com API
- Two-token auth: `connect_token` (user-specific, ephemeral) + `site_token` (per-site, persistent)
- Auto-creates WooCommerce API keys (consumer_key/secret) and WordPress Application Password for a dedicated `wc_api_app_*` user
- Provides embedded AI chat sidebar for WordPress admin
- WooCommerce integration for e-commerce features
- Non-blocking webhooks for product/order sync

## Setup Wizard (3 steps, since v1.7.04)
1. **Connect** — Paste Connect Secret, auto-creates WooCommerce keys + app user
2. **Indexing** — Live indexing progress (products, orders, customers count up), AI profile analysis, 10min timeout
3. **Complete** — AI Store Insights panel, profile auto-saved

Key JS functions (global scope, no IIFE — required for inline onclick handlers):
- `showStep(n)` — navigate between wizard steps with fade-in animation
- `startSetupPolling()` — polls AJAX endpoint for indexing progress and AI analysis
- `saveProfileSilently(profile)` — auto-saves profile without user interaction
- `checkConnectReady()` — pulses Connect button when input is filled
- `skipSetup()` — skip and complete later
- `finishOnboarding()` — marks onboarding complete

## Key Features
- **AI Sidebar** — iframe on all admin pages (`app.peligent.com/frontend/dashboard/assistant?embed=true`), resizable, maximizable, lazy-loaded, token via postMessage
- **Target mode** — click crosshair to select page elements and ask AI about them
- **Page context detection** — sidebar knows current WP admin page (product list, order edit, blog editor, etc.)
- **Iframe pages** — Bulk Update, Blog Update, Action History, Bots, Reports, Integrations (all from app.peligent.com)
- **Content generation** — "Generate with Peligent" buttons on product editor + blog editor
- **Blog image generation** — modal with embedded image generator
- **Quick Add / Bulk Import** — URL-based product import on product list page
- **Pulse Dashboard Widget** — AI insights on WP dashboard
- **Floating chat toggle** — configurable in settings
- **Media library integration** — image editing / background removal

## Key PHP Methods
- `perform_connection()` — main connection logic, auto-creates keys/passwords
- `render_admin_page()` — routes to wizard or settings page
- `render_wizard()` — 3-step setup wizard with live indexing stats
- `render_settings_page()` — post-setup settings with collapsible cards
- `render_sidebar_on_all_pages()` — AI chat sidebar with page context
- `admin_assets()` — enqueues CSS/JS and defines content generation functions
- `render_product_list_modals()` — Quick Add / Bulk Import modals
- `render_blog_image_modal()` — blog image generation modal
- `handle_overview_endpoint()` — REST API: store overview data
- `send_product_webhook()` / `send_order_webhook()` — real-time sync (non-blocking)
- `ajax_connect()` / `ajax_poll_profile()` / `ajax_trigger_profile()` — AJAX handlers
- `fetch_profile_settings()` / `push_profile_settings()` — bidirectional profile sync
- `peligent_ai_assistant_uninstall()` — cleanup: deletes options, notifies backend, removes app user

## Important Conventions
- All PHP output uses `esc_html__()`, `esc_attr()`, `esc_url()` for security
- AJAX handlers use `wp_verify_nonce()` for CSRF protection
- Application Passwords force-enabled even on non-HTTPS setups
- Webhooks are non-blocking (`'blocking' => false`) — never slows down the store
- Inline JS uses `echo '...'` statements in PHP — be careful with quote escaping
- CSS split between inline `<style>` blocks and external files in assets/
- Uninstall hook cleans up all options and notifies Peligent backend