=== Autouzupełnianie adresów (GEO-01) ===
Tags: woocommerce, checkout, address, autocomplete, poland
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Requires Plugins: woocommerce
Stable tag: 0.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Address suggestions and address verification for Polish addresses in the WooCommerce checkout, based on official Polish address data.

== Description ==

This plugin helps customers enter correct Polish addresses in the WooCommerce checkout. While the customer types the street and house number, it suggests matching addresses from official Polish address data, fills in the street, postcode and city with one click, and, after the customer leaves the address fields, checks that the address exists.

**Features**

* Address suggestions from the third typed character, tolerant to typos and missing Polish diacritics ("warszwska 10 otwo" finds "Warszawska, Otwock").
* One click fills the street and number, the postcode and the city.
* Works in the classic checkout (shortcode), in the block-based Checkout and on the address edit page in My account, for billing and shipping addresses. Active only when the selected country is Poland; changing the country switches it off and on again.
* Verification after the customer leaves the address fields, with a clear message in Polish: confirmed, probable, house number not found, address not found. If the address is not confirmed, the customer can tick "My address is correct".
* Three modes: **Off**, **Warn** (default: never blocks the order) and **Block** (does not submit the form while the address is known to be wrong, unless the customer ticks "My address is correct"). Verification never blocks the order when the address service is unavailable.
* Accessible: ARIA combobox pattern, full keyboard support, large touch targets, light and dark appearance.
* Privacy-friendly: no cookies, nothing is stored in the browser, no browser location (geolocation) requests.
* Compatible with High-Performance Order Storage (HPOS) and with the Cart and Checkout blocks. The plugin does not read or modify orders.
* No code is loaded from third-party servers: the scripts are bundled with the plugin.

**What you need**

The plugin does not contain address data. It needs the address of an address API (see "External services" below), entered in WooCommerce > Autouzupełnianie adresów (GEO-01). Until the address is set the plugin does nothing and sends nothing.

The address API is GEO-01 by Orbispect P.S.A.: https://orbispect.com/geo-01/ . Enter https://orbispect.com/geo-01 as the address on the settings page. For now the service can be used without a key, with a usage limit per IP address; keys with higher limits and paid plans will be added later.

== External services ==

This plugin connects to an external address API (the "Address API") to provide address suggestions and address verification in the WooCommerce checkout. The address of the Address API is entered by the site owner on the plugin settings page. The plugin does nothing and sends nothing until it is set.

What the service is used for: suggesting addresses while the customer types the street and house number, and checking that the entered address exists in official Polish address data (state geodetic and cartographic resources).

What data is sent and when:

* While the customer types in the street field of the checkout or of the address edit page (only when the selected country is Poland): the typed fragment of the address (at least 3 characters, sent after a 250 ms pause in typing), a random one-time session identifier generated in the browser and not stored, the optional API key and the number of results. The request goes directly from the customer's browser to the Address API.
* When the customer leaves the address fields, unless the address was picked from the suggestions: the address composed of the street, postcode and city fields, the same session identifier and the optional API key (one verification request).
* Like with every HTTP request, the server of the Address API receives the customer's IP address and standard browser headers (for example User-Agent and the address of the shop website in the Origin header).
* On the settings page, when an administrator clicks "Test connection": the server of the shop sends one request to the /v1/info route of the Address API. It contains no customer data.

The plugin does not send names, e-mail addresses, phone numbers or order data. It does not use cookies and does not store anything in the browser.

Service provider: Orbispect P.S.A., ul. Złota 75A/7, Warszawa, Poland (https://orbispect.com/)

Terms of service: https://orbispect.com/pl/terms

Privacy policy: https://orbispect.com/pl/privacy

The suggestions show a short notice about the source of the address data (state geodetic and cartographic resources). It can be switched off in the settings.

== Installation ==

1. Install and activate WooCommerce (7.0 or newer).
2. Upload the plugin to the `/wp-content/plugins/` directory or install it from the Plugins screen, then activate it.
3. Go to WooCommerce > Autouzupełnianie adresów (GEO-01), enter the address of the Address API (and the key, if you have one), choose the verification mode and click "Test connection".
4. Save the settings. Open the checkout and type an address in the street field (country: Poland).

== Frequently Asked Questions ==

= Does it work with the block-based checkout? =

Yes. It works with the classic checkout (shortcode) and with the Checkout block, for billing and shipping addresses.

= Does it block orders with wrong addresses? =

Not by default. In the default mode (Warn) it only shows a message and a "My address is correct" checkbox. The Block mode, which you must choose yourself, does not submit the form while the address is known to be wrong, unless the customer ticks the checkbox. If the address service is unavailable the order is never blocked.

= Which data is sent to the address service? =

The typed part of the address, a random session identifier and the optional key; see "External services" above. Names, e-mail addresses, phone numbers and order data are never sent.

= Which countries are supported? =

Only Poland (the address register covers Poland). For other countries the plugin does nothing.

= Can I change the colours? =

Yes. The suggestions and messages use CSS variables (for example --adr-accent, --adr-bg, --adr-fg) that you can override in your theme.

= Where is the source code of the minified script? =

The human-readable source is bundled in `assets/js/adresy-widget.js`. The minified file `assets/js/adresy-widget.min.js` is produced from it with esbuild (`esbuild adresy-widget.js --minify --target=es2018`).

== Changelog ==

= 0.1.0 =
* First version.

== Upgrade Notice ==

= 0.1.0 =
First version.
