=== ScriptSpy - Third-Party Script Intelligence ===
Contributors: loyaltyoverroyalty
Tags: gdpr, privacy, scripts, audit, compliance
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 8.2
Stable tag: 1.0.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Detect every third-party script loading on your site, identify owners, data collected, and export a GDPR audit report your lawyer can use.

== Description ==

ScriptSpy is a focused script intelligence dashboard. It is **not** a cookie banner and **not** a consent wizard — those tools already exist. ScriptSpy answers one question:

**"What is loading on my site, who owns it, what data does it collect, and give me a PDF I can show my lawyer."**

= Two-layer detection =

* **Server-side scan** — fetches your own pages with `wp_remote_get` and parses HTML with `DOMDocument` to extract every external script, iframe, preconnect hint, and tracking pixel. Catches statically loaded scripts.
* **Browser beacon** — a JavaScript beacon you can run in a real browser (logged-in admin or anonymous via signed token URL). Uses `PerformanceObserver`, `MutationObserver`, and intercepts `fetch`, `XMLHttpRequest`, and `navigator.sendBeacon` to capture every dynamically loaded resource — including pixels that Google Tag Manager loads after page render.

= What you get =

* Live dashboard with summary cards: total scripts, known/identified, require consent, unrecognized
* Per-script detail modal: owner, country, data collected, legal basis, GDPR relevance, data transfer destination, Schrems II notes, links to privacy policy and DPA
* PDF audit report (cover, executive summary, full inventory, unknown scripts list)
* CSV export
* Cookie + localStorage detection
* Scan history with diff between scans (added/removed scripts)
* Optional weekly/monthly automated scans with email reports
* Knowledge base of 70+ third-party services (Google Analytics, Meta Pixel, TikTok, Hotjar, Stripe, Intercom, etc.)

= Anonymous beacon mode =

GTM rules often suppress pixels for logged-in WordPress administrators. ScriptSpy generates a tokenized scan URL you can open in incognito to capture those pixels — without exposing the beacon to your real visitors.

= Privacy =

ScriptSpy makes no external HTTP requests except scanning your own site. No telemetry, no phone-home, no third-party API calls. The bundled knowledge base is a static JSON file shipped with the plugin.

== Installation ==

1. Upload the `scriptspy` folder to `/wp-content/plugins/`.
2. Activate via Plugins menu in WordPress.
3. Go to Tools → ScriptSpy.
4. Click **Start new scan**.
5. Open the anonymous scan URL in an incognito window and browse a few pages so the beacon can capture dynamically loaded scripts.
6. Return to the dashboard, review results, download PDF or CSV.

== Frequently Asked Questions ==

= Does this replace a cookie consent banner? =

No. ScriptSpy detects and reports — it does not block scripts or show banners to visitors. Use it alongside a consent platform.

= Will it slow down my site? =

The server scan runs in batches via WP-Cron, not on visitor requests. The browser beacon is injected only for logged-in admins or visitors carrying a valid scan token — never for normal traffic.

= Can it detect server-side conversion APIs (e.g., Meta Conversions API)? =

No. Server-to-server calls are invisible to client-side detection by design. ScriptSpy lists known server-side endpoints in its knowledge base for awareness but cannot confirm whether they fire.

= Why are some pixels missing from the report? =

Many GTM containers exclude logged-in WordPress administrators from firing pixels. Use the **anonymous scan URL** in an incognito browser to capture those pixels.

= Does the PDF require any external libraries? =

The plugin bundles TCPDF 7 (via Composer) and the Helvetica core font definitions it needs. If TCPDF is unavailable for any reason, ScriptSpy falls back to a styled HTML report download.

== Screenshots ==

1. Main dashboard: summary cards, filters, and the results table with owner, category, data collected and GDPR level for every script.
2. Script detail: owner, country, data collected, legal basis, data transfer destination, Schrems II note, and every page the script was found on.
3. Scan in progress: server scan percentage, live browser-beacon status, and the anonymous scan URL.
4. Diff between two scans - scripts added and removed.
5. PDF audit report: executive summary and full script inventory.
6. Scan history with per-scan PDF and CSV export, plus diff against the previous scan.
7. Settings: scan depth, scheduled scans, email reports and excluded domains.

== Changelog ==

= 1.0.2 =
* Fixed: inline-detected scripts (Google Analytics, Meta Pixel, Intercom and others recognised from inline snippets) showed a knowledge base id where the domain belongs. They are now labelled "inline script".
* Fixed: the Google Analytics 4 measurement endpoint (`/g/collect`) was not in the knowledge base, so GA4 traffic captured by the browser beacon was counted as unrecognized.
* Fixed: long privacy policy and page URLs overlapped the following line in the PDF script inventory.
* Knowledge base updated to v1.0.1.

= 1.0.1 =
* Upgraded bundled TCPDF to 7.0.7 (now requires PHP 8.2+).
* Generic CDN hosts are now classified through the bundled knowledge base instead of a hard-coded list.
* Browser beacon is enqueued through `wp_enqueue_scripts`.
* Hardened scan-token validation, CSV export and settings sanitization.

= 1.0.0 =
* Initial release.
* Two-layer detection: server-side DOMDocument scan + browser beacon.
* Anonymous tokenized beacon mode for capturing pixels GTM hides from admins.
* PDF and CSV export.
* Cookie and localStorage detection.
* Scan history and diff.
* Bundled knowledge base of 70+ third-party services.

== Upgrade Notice ==

= 1.0.2 =
Bug fixes only: correct labelling for inline-detected scripts, GA4 measurement endpoint recognised, PDF layout fix.

= 1.0.1 =
Requires PHP 8.2 or newer because of the TCPDF 7 upgrade.

= 1.0.0 =
Initial release.