=== NexusDesk — Economic Nexus & Sales Tax Filing Reports for WooCommerce ===
Contributors: lijnam
Tags: woocommerce, sales tax, economic nexus, tax report, filing report
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 0.2.5
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Turn WooCommerce order tax into per-state filing reports and track each state's economic-nexus threshold with its real test.

== Description ==

US stores that sell into more than one state have to file sales tax state by state and watch economic-nexus thresholds at the same time. WooCommerce records tax per rate code and per order, but it has no filing report a bookkeeper can hand to a state, no transaction counts measured against that state's threshold, and no county/city/district split. Owners export orders and rebuild the numbers in a spreadsheet every filing period, and a threshold measured on the wrong test means back taxes and penalties.

NexusDesk reads the tax already stored on WooCommerce orders and produces a filing report for one state and one date range. It separates gross sales, taxable sales and tax collected, keeps refunds, cancelled orders and exempt or zero-rated orders out of the taxable base, groups the result by tax rate and rate code, and exports a CSV and a print view. It reads orders through the WooCommerce CRUD API, so it is HPOS compatible and never queries the posts tables for order data. No order, customer or tax data leaves the site; the only outbound request is the licence check disclosed under External Services below.

The separate Pro add-on turns that report into a multi-state nexus monitor. It applies each state's own test — revenue-only states are never triggered by a transaction count, and states that use a revenue-and-transactions test use the combination the state actually publishes — over the correct measurement period for that state, shows progress against each threshold, and emails the store when a threshold is approaching. Pro also splits home-rule local taxes into county, city and district components and reconciles them to the state total, includes subscription renewal orders in the count, and produces accountant-ready export packs.

**Free features**

* Accurate single-state filing report: gross sales, taxable sales, tax collected, order count and refunds, grouped by tax rate and rate code.
* Refunds, cancelled/failed orders and exempt or zero-rated orders are separated and excluded from the taxable base.
* CSV export plus a one-page print view.
* HPOS compatible, and it degrades to an admin notice instead of a fatal error when WooCommerce is inactive. No order data leaves the site.
* State rules table with an official source URL and review date for every state.

= Pro and Agency =

NexusDesk — Economic Nexus & Sales Tax Filing Reports for WooCommerce is free. Pro ($59) and Agency ($99) add 9 more capabilities.

The free plugin works on its own — nothing above is a trial, and nothing switches off when a licence is missing. What the paid tiers add:

* Multi-state economic-nexus dashboard that applies each state's real test: revenue-only states are never triggered by transaction count, and revenue-plus-transaction states use the correct combination.
* The correct measurement period per state (calendar year, rolling twelve months, prior calendar year) with progress against each threshold and email alerts as a threshold approaches.
* County, city and district/special-district breakdown for home-rule states, reconciled to the state total.
* WooCommerce Subscriptions renewal orders included in the thresholds and reports, with a toggle to exclude them.
* Accountant-ready per-state export pack: CSV plus a printable filing summary with audit totals.
* Multisite network roll-up: one screen showing every store's nexus position, without mixing currencies or store data.
* Per-client filing report packs with scheduled email delivery.
* White-labelled reports that remove the plugin's branding from exported and emailed reports.
* Role-based read-only accountant access through a dedicated capability.

See everything each tier includes: https://tillfoundry.com/product/nexusdesk-pro/

= Where the numbers come from =

The bundled state rules table lists each state's revenue threshold, transaction threshold, test and measurement period, each with the official state revenue-department source URL and the date it was reviewed. Rules are overridable with the `nexusdesk_state_rules` filter, and the review date is shown on screen. The table is a starting point, not tax advice: always confirm the current threshold with the state.

= Does this file my return? =

No. NexusDesk produces a report of the tax your store already collected and shows the figures a state expects. It does not file, e-file, remit or pay a return, and it does not calculate tax at checkout. It is not tax advice.

== Installation ==

1. Install the ZIP through Plugins → Add New → Upload Plugin, or upload the plugin folder to `/wp-content/plugins/`.
2. Activate the plugin through the Plugins screen.
3. Open NexusDesk in the admin menu (its own top-level menu, next to WooCommerce) to build a filing report. No licence key is needed for the free report.
4. To use Pro or Agency, install the separate **NexusDesk Pro** add-on ZIP that came with your purchase, activate it alongside this plugin, then enter your licence key under NexusDesk → Settings → Licence. The key is issued for the add-on, so this is the screen that activates it: paste it, click Save Changes, and the Licence tab reports the plan it bought.

== External Services ==

This plugin connects to the TillFoundry licence server at `https://tillfoundry.com` only when you enter a licence key, to activate and validate that key. The separate Pro add-on, when installed and licensed, also uses that server to check for its own updates; the free plugin itself takes its updates from the WordPress.org directory. Each request sends the licence key, the site URL and home URL, the plugin slug and version, the WordPress version, the PHP version, whether the site is multisite, and the site locale; the server records the request IP address. It sends no order, customer, tax or report data. Reports are built and cached entirely on your own server, and no other external service is contacted. The service's terms of service are at https://tillfoundry.com/terms/ and its privacy policy is at https://tillfoundry.com/privacy-policy/.

== Frequently Asked Questions ==

= Does it need WooCommerce? =

Yes at runtime. NexusDesk reads WooCommerce orders and their taxes. It does not declare a hard `Requires Plugins` header, so it activates safely on a site without WooCommerce and shows an admin notice explaining what is missing instead of fataling.

= Does any data leave the site? =

No. Order and tax data stays in your database. The only outbound request is the licence validation described under External Services, which sends the licence key and basic site and version information.

= Does it work with HPOS? =

Yes. Orders are read through the WooCommerce CRUD API (`wc_get_orders()` and the `WC_Order` getters), never through the posts tables, so behaviour is identical with HPOS enabled or disabled. NexusDesk declares compatibility with custom order tables on WooCommerce → Status → Compatibility.

= What order statuses are counted? =

Completed, processing and on-hold by default, configurable on the settings screen. Refunds, cancelled and failed orders are separated out.

= How are exempt sales handled? =

An order with a positive total but no tax, a tax-exempt customer flag, an exemption-certificate reference, or only zero-rate tax lines is treated as exempt and excluded from the taxable base. The free report counts it as exempt so the filing total is not overstated.

= Where do the thresholds come from? =

From the bundled rules table, which cites each state's official revenue-department page and its review date. Every value is overridable with the `nexusdesk_state_rules` filter.

= I bought NexusDesk Pro. How do I install the add-on and enter my licence? =

Your purchase confirmation includes the NexusDesk Pro add-on ZIP. In your WordPress admin, go to Plugins → Add New → Upload Plugin, choose that ZIP, install it, and activate **NexusDesk Pro**. Keep the free NexusDesk plugin active: the add-on does nothing without it. Then open NexusDesk → Settings → Licence, paste your licence key and save. The Nexus Monitor unlocks immediately. The same steps are on the NexusDesk dashboard. If your confirmation has no add-on download link, email support@tillfoundry.com with your order number and we will send it before you buy anything else.

= Is the Pro add-on a separate download? =

Yes. This plugin directory download is the free plugin, and it contains only the free filing report. Pro and Agency are delivered by the separate NexusDesk Pro add-on. Once that add-on is active and licensed, its screens and capabilities appear inside this plugin.

== Screenshots ==

1. The filing report with gross, taxable, tax, refund and order-count cards.
2. The per-rate-code table with CSV export and print view.
3. The multi-state nexus monitor with threshold progress (Pro).
4. The local jurisdiction breakdown reconciled to the state total (Pro).
5. The settings screen with the free/Pro/Agency boundary.

== Changelog ==

= 0.2.5 =
* **The developer build script no longer ships in the download.** `bin/build-dist.sh` was included in the distributable package, and WordPress.org's Plugin Check refuses any plugin that contains an application file (`application_detected`), so the directory would have pended the submission rather than approved it. `/bin/` is now excluded from the ZIP, matching the plugin's siblings. No report figure, setting, route, capability or paid gate changed.

= 0.2.4 =
* **Shared admin-UI consistency pass.** The overview, Filing Reports, the Nexus Monitor and Settings now open with the same header — title, running version badge and a one-line purpose — the upgrade prompt, post-purchase guide and report form share one card surface, and the report table's header and total rows align consistently. No report figure, setting, route or capability changed.
* **A licence save now activates once.** Pasting a key and pressing Save made the site call the licence server dozens of times in a few seconds until it was rate-limited, stacked a notice per attempt, and could leave the key unsaved. The sanitiser re-entered itself through the option write, and WordPress passes an empty value when another form is saved — which was read as "remove the licence". Both are guarded now.

= 0.2.3 =
* **NexusDesk now shows its own version on its own admin screens.** The version sits beside the title on the overview and is appended to the admin footer on every NexusDesk screen — the overview, Filing Reports, the Nexus Monitor and Settings — read from `NEXUSDESK_VERSION`, the same constant the plugin header and the asset cache-buster use. The footer is left untouched on every other admin page.

= 0.2.2 =
* Rebuilt the free download so the live free-download route stops serving the pre-fix 0.2.0 build. The 0.2.1 licence-client fix that lets a Pro or Agency key activate is included; this release exists so the release pipeline refreshes the artifact served from the free-download route.
* Aligned the Pro and Agency activation limits in this readme with the store: Pro covers 3 site activations and Agency covers 10.

= 0.2.1 =
* Corrected the price in the free plugin's readme: Pro is $59/year, not $79/year, matching the store and the add-on's product record. Agency stays $99/year.
* A Pro or Agency licence key now activates on this plugin. The licence client presents the add-on's own slug (`nexusdesk-pro`) when the add-on is installed, retries when the store answers `plugin_mismatch`, and remembers the slug the key was accepted for. Before this, every key sold for the add-on was refused with "This licence was issued for a different plugin".
* NexusDesk is now its own top-level admin menu; the dashboard, Filing Reports, Nexus Monitor and Settings are its submenus.

= 0.2.0 =
* Added a post-purchase guide on the NexusDesk dashboard with the exact download, install and licence steps for the separate Pro add-on; a purchase button appears only when a live purchase URL and a verified add-on download route are both supplied.
* Corrected the description, which wrongly said Pro and Agency unlock on this plugin with "no second download"; the paid capabilities are delivered by the separate NexusDesk Pro add-on.

= 0.1.2 =
* The Licence settings section is registered only when a paid NexusDesk add-on is loaded, and its internal "purchase receipt" / "until the product page is published" copy is removed. Free-only installs no longer see a licence form they cannot use. A purchase link appears only once a live SKU URL is supplied through the `nexusdesk_license_purchase_url` filter.

= 0.1.1 =
* Removed the self-hosted update checker from the free plugin so it passes WordPress.org's Plugin Check (`plugin_updater_detected`). The free plugin now takes its updates from the WordPress.org directory; the separate Pro add-on carries its own updater in the paid tree.

= 0.1.0 =
* First release. Single-state filing report, refund and exemption handling, per-rate grouping, CSV export and print view. Bundled, versioned US state rules table with provenance. HPOS compatible. Separate Pro add-on adds multi-state nexus monitoring, threshold alerts, jurisdiction breakdown, subscription renewal inclusion and accountant export packs.

== Upgrade Notice ==

= 0.2.5 =
Stops the developer build script from shipping in the download, so WordPress.org's Plugin Check passes. No report, setting or data change.

= 0.2.4 =
Shared admin-UI consistency pass across the plugin's four screens. No report figure, setting, route or capability changes.

= 0.2.2 =
Refreshes the free download so it includes the licence-client fix that lets a Pro or Agency key activate. No report, setting or data change.

= 0.2.1 =
Corrects the readme's Pro price to $59/year and lets a Pro or Agency key activate on this plugin. Free reports, settings and data are unchanged.

= 0.2.0 =
Adds post-purchase install instructions for the separate Pro add-on. No report, setting or licence change for existing installs.

= 0.1.2 =
Hides the Licence settings section and its internal copy unless a paid add-on is active. No report or settings change for free users.

= 0.1.1 =
Removes the self-hosted update checker from the free plugin so WordPress.org's Plugin Check passes. No report or settings change.

= 0.1.0 =
Initial release.
