=== CompanyStack – UK Company Search & Directory ===
Contributors: swilson23
Tags: companies house, company search, autocomplete, woocommerce, business directory
Requires at least: 6.3
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.1.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

UK company autocomplete that fills in forms and WooCommerce checkouts, plus company profile cards, company status badges and a business directory.

== Description ==

CompanyStack connects your site to Companies House register data, kept up to date by CompanyStack, for the companies on the UK register. Customers type the first few letters of their company name, pick it from the list, and the registration number and registered office address are filled in for them. No more mistyped company numbers on B2B orders, account applications or quote requests.

**What you get**

* **Company autocomplete with form auto-fill.** Works with the Company Search block or `[companystack_search]`, with Contact Form 7, WPForms and Gravity Forms (add a CSS class to your fields), and with any HTML form (data attributes).
* **WooCommerce B2B checkout.** The checkout Company field suggests UK companies and fills in the address. An optional "Company registration number" field is filled automatically, validated and saved with the order. Works with both the Checkout block and the classic checkout, and is compatible with High-Performance Order Storage.
* **Company profile card.** Status, company number, type, incorporation date, registered office, nature of business (SIC codes) and accounts and confirmation-statement due dates, with overdue warnings.
* **"Active UK company" status badge.** Show visitors that your business (or a supplier, member or client) is registered and active at Companies House, linked to the official record. The badge hides itself automatically if the company stops being active. It shows the register entry only: it does not verify who runs the website it appears on.
* **UK business directory.** List companies by SIC code, postcode area, town or name, with an optional visitor search form. Ideal for trade associations, local business listings and industry directories.

Each feature is available as a block and as a shortcode.

**Built to be safe and light**

* Your API key stays on your server. Browsers only talk to your own site's REST API, which calls CompanyStack server-side.
* Visitor searches are protected by a nonce and a per-visitor rate limit, so nobody can burn through your allowance.
* Answers are cached (one day by default) to keep pages fast and API usage low.
* No jQuery, no tracking, no admin nags, no front-end credit link unless you switch it on.
* Blocks are built with core WordPress components; there is no heavy JavaScript bundle.

**About the CompanyStack service**

This plugin is an interface to the CompanyStack API (see "External services" below), which does the work of searching and serving Companies House records. You need a CompanyStack API key. The free plan needs no payment card and covers company search, autocomplete (up to 5 suggestions), company profiles, badges and directories of up to 10 results. Paid plans raise the daily request limits and allow larger, paginated directories. Every feature of the plugin works on the free plan; see [companystack.co.uk/pricing](https://companystack.co.uk/pricing) for limits and prices.

== External services ==

This plugin connects to the **CompanyStack API** at `https://api.companystack.co.uk`, operated by CompanyStack, to look up UK company information derived from the public Companies House register. It cannot work without this service.

**When requests are made**

* When a visitor types at least two characters into a CompanyStack company search field (including the WooCommerce checkout Company field when enabled) and pauses: the typed text is sent to find matching companies.
* When a visitor chooses a company from the suggestions: its company number is sent to fetch the full record used to fill the form.
* When a page containing a company card, status badge or directory block or shortcode is displayed and the answer is not already cached: the company number, or the directory filters (SIC code, postcode, town, name and status, including any search a visitor enters in the directory form), are sent.
* When an administrator clicks "Test connection" on the settings screen: a sample search is sent to check the key.

**What is sent**

Only the search text, company number or directory filters described above, together with your site's CompanyStack API key (to identify your account) and a user-agent string naming this plugin and its version. Requests are made from your web server; visitors' IP addresses, cookies and other form fields are **not** sent. Nothing is sent until an API key has been saved, and the plugin does not collect usage statistics.

* CompanyStack terms of service: https://companystack.co.uk/terms
* CompanyStack privacy policy: https://companystack.co.uk/privacy

Company data originates from Companies House and is provided under the Open Government Licence v3.0. Company pages link to the official Companies House service (find-and-update.company-information.service.gov.uk); those links are ordinary hyperlinks and send nothing unless a visitor clicks them.

== Installation ==

1. Install the plugin from Plugins › Add New (search for "CompanyStack"), or upload the `companystack` folder to `/wp-content/plugins/`, then activate it.
2. Get a free API key at [companystack.co.uk/signup](https://companystack.co.uk/signup).
3. Go to **Settings › CompanyStack**, paste the key, click **Test connection**, then **Save Changes**.
4. Add a CompanyStack block (Company Search, Company Profile Card, UK Company Status Badge or UK Business Directory) or a shortcode to any page.

Optionally, put the key in `wp-config.php` instead of the database:

`define( 'COMPANYSTACK_API_KEY', 'cs_your_key_here' );`

== Frequently Asked Questions ==

= Is it free? =

The plugin is free and open source (GPL). It needs a CompanyStack API key; the free plan requires no card and runs every feature, with smaller limits. Paid plans are for busier sites that need more requests per day or bigger directories.

= Is my API key exposed to visitors? =

No. The key is only used by your web server. Visitors' browsers call your site's own REST endpoints (`/wp-json/companystack/v1/…`), which are nonce-protected and rate limited per visitor.

= How do I auto-fill a Contact Form 7 form? =

Add CSS classes to the form tags:

`[text company class:companystack-autocomplete]`
`[text company-number class:companystack-fill-company_number]`
`[text address class:companystack-fill-address_line_1]`
`[text town class:companystack-fill-town]`
`[text postcode class:companystack-fill-postcode]`

The script loads automatically on pages with such a form.

= How do I auto-fill WPForms or Gravity Forms? =

Open the field's Advanced settings and enter `companystack-autocomplete` in "CSS Classes" for the company name field, and `companystack-fill-postcode` (etc.) for the fields to fill. Available fields: `company_number`, `address_line_1`, `address_line_2`, `town`, `county`, `postcode`, `country`, `address` (the whole address on one line), `company_status`, `company_type`, `date_of_creation` and `sic_codes`.

= How do I auto-fill my own HTML form? =

Mark the fields with data attributes and add `[companystack_autofill]` (or the Company Search block) to the page:

`<input name="company" data-companystack-autocomplete>`
`<input name="number" data-companystack-fill="company_number">`
`<input name="postcode" data-companystack-fill="postcode">`

Developers can also map fields by CSS selector with the `companystack_autofill_targets` filter, and listen for the `companystack:select` browser event, whose `detail.company` holds the chosen company.

= How does the WooCommerce integration work? =

With WooCommerce active, the checkout Company field suggests UK companies, and choosing one fills in address line 1 and 2, town, county and postcode, plus the company registration number field. The number is validated and saved with the order and shown in the order screen and emails. With the Checkout block, first make the Company field visible in the block's settings. Both options can be switched off under Settings › CompanyStack.

= Which shortcodes are there? =

* `[companystack_search label="Company name" name="company_name" number_name="company_number" show_details="true"]`
* `[companystack_card number="00445790" show_address="true" show_sic="true" show_filings="true"]`
* `[companystack_badge number="00445790" show_name="true" link="true" show_inactive="false"]`
* `[companystack_directory sic="62012" postcode="M1" town="" query="" status="active" limit="10" layout="list" show_filter="false"]`
* `[companystack_autofill]`

= I use full-page caching. Will search still work? =

Search requests carry a WordPress nonce, which is valid for up to 24 hours. If your cache keeps pages longer than about 12 hours, exclude the pages with company search forms (for example the checkout) or lower the cache lifetime. Cards, badges and directories are rendered on the server and cache normally.

= My site is behind a proxy or CDN. Is rate limiting per visitor? =

By default the limit uses the connecting IP address, which behind a proxy may be the proxy's. If your proxy sets a trusted header, return the real address with the `companystack_client_ip` filter.

= What happens if the service is unavailable or my limit is reached? =

Forms keep working as normal text fields, cards, badges and directories are simply left out for visitors, and administrators see an explanatory notice on the page and on the settings screen. The plugin pauses requests briefly after errors so it never slows your site down.

= What data does the plugin store? =

Settings (including the API key) in one option, cached API answers and short-lived rate-limit counters as transients, and, if enabled, the company registration number on WooCommerce orders. Deleting the plugin removes everything except order data.

== Screenshots ==

1. Company autocomplete filling in a contact form.
2. WooCommerce Checkout block with the Company field suggesting UK companies.
3. Company profile card.
4. "Active UK company" status badge.
5. UK business directory with the visitor search form.
6. Settings › CompanyStack.

== Changelog ==

= 1.1.2 =
* Clearer description: company data comes from the Companies House register as held and updated by CompanyStack, not from live Companies House calls.
* Tested with WordPress 7.1.

= 1.1.1 =
* The badge now reads "Active UK company" and, on hover, says it shows the register entry only and does not verify who runs the website. The block is renamed UK Company Status Badge; existing blocks and shortcodes keep working.
* The source line under cards and directories says the data comes from Companies House via CompanyStack, which accepts no responsibility to anyone who relies on it, and to check important information against the official record. This keeps sites that show CompanyStack data in line with its Terms (clause 15B).

= 1.1.0 =
* Rebuilt on the CompanyStack API at api.companystack.co.uk; the old API address no longer works, so please update.
* Security: the API key is no longer sent to browsers. All look-ups go through nonce-protected, rate-limited REST endpoints on your own site.
* New: blocks for Company Search, Company Profile Card, Verified UK Company Badge and UK Business Directory.
* New: WooCommerce checkout company autocomplete and company registration number field (Checkout block and classic checkout, HPOS compatible).
* New: auto-fill for Contact Form 7, WPForms, Gravity Forms and any HTML form via CSS classes or data attributes.
* New: business directory by SIC code, postcode area, town or name, with optional visitor search and pagination on paid plans.
* New: settings screen with connection test, plan limits, cache controls and a privacy-policy suggestion.
* Removed jQuery dependency, activation redirect and unused CRM code.
* Uninstall now removes all settings and cached data.

= 1.0.0 =
* Initial release.

== Upgrade Notice ==

= 1.1.2 =
Wording and compatibility update; no changes to settings.

= 1.1.1 =
Clearer badge and source wording, needed to keep showing CompanyStack data under its updated Terms.

= 1.1.0 =
Required update: version 1.0 used an API address that has been retired. Your saved API key is carried over; check it with "Test connection" under Settings › CompanyStack.
