=== Qapla' Pudo ===
Contributors: qaplawoocommerce
Tags: pudo, collection, points, shipping, shipment
Requires at least: 6.3
Tested up to: 6.9
Stable tag: 2.03
Requires PHP: 8.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Collection points for your shipments.

== Description ==

Collection points for your shipments. This plugin integrates with Qapla' and GLS services to provide pickup point (PUDO) selection during WooCommerce checkout.

== Installation ==

1. Upload the plugin folder to the `/wp-content/plugins/` directory, or install it directly from the WordPress plugin directory.
2. Activate the plugin from the "Plugins" menu in WordPress.
3. Go to **Qapla' Pudo** in the WordPress admin menu and enter your API credentials (Qapla' or GLS).
4. Go to **WooCommerce > Settings > Shipping**, add a shipping zone and add "Qapla' Pudo" as a shipping method.
5. Configure the map type, radius, and tracking options as needed.

== Third Party Services ==

This plugin connects to the following external services:

= Qapla' API =
* Service URL: https://api.qapla.it
* Purpose: Retrieve pickup points (PUDO) near a shipping address, and retrieve the list of available couriers (admin settings page only).
* Terms of Service: https://www.qapla.it/terms-and-conditions/
* Privacy Policy: https://www.qapla.io/privacy-policy
* Data transmitted: Shipping address (postcode, city, country, street) is sent on checkout to find nearby pickup points. The private API key is sent with each request for authentication. For the couriers list, only the private API key is transmitted (no user data).

= GLS Italy API =
* Service URL: https://api.sellsend2.gls-italy.com
* Purpose: Alternative API for GLS pickup points (when GLS platform is selected)
* Terms of Service: https://www.gls-italy.com/it/chi-siamo/legal/condizioni-di-trasporto/
* Privacy Policy: https://gls-group.eu/IT/it/privacy-policy
* Data transmitted: Shipping address (postcode, city, street) to find nearby pickup points

= OpenStreetMap Nominatim =
* Service URL: https://nominatim.openstreetmap.org
* Purpose: Geocoding service to convert addresses to coordinates for map display
* Terms of Service: https://operations.osmfoundation.org/policies/nominatim/
* Privacy Policy: https://wiki.osmfoundation.org/wiki/Privacy_Policy
* Data transmitted: Shipping address for geocoding

= Google Maps API (Optional) =
* Service URL: https://maps.googleapis.com
* Purpose: Map display when Google Maps view is configured by the user
* Terms of Service: https://cloud.google.com/maps-platform/terms
* Privacy Policy: https://policies.google.com/privacy
* Data transmitted: User location data for map rendering
* Note: Requires user to provide their own Google Maps API key

= Qapla' Tracking Service =
* Service URL: https://tracking.qapla.it, https://api.qapla.it and https://cdn.qapla.it
* Purpose: Display shipment tracking widget and live status on the order detail page. Shipment event status icons are loaded from https://cdn.qapla.it as part of the tracking data returned by the Qapla' API.
* Terms of Service: https://www.qapla.it/terms-and-conditions/
* Privacy Policy: https://www.qapla.io/privacy-policy
* Data transmitted: Tracking number and API key are sent to retrieve tracking events. Status icon images are loaded directly from cdn.qapla.it as part of the service response.
* Note: Only active when a tracking number has been assigned to the order and the Tracking View setting is not set to "Hide tracking".

== Development ==

= Building Assets =

The plugin uses npm for building JavaScript assets. To build:

1. Navigate to the plugin directory
2. Run `npm install` to install dependencies
3. Run `npm run build` to build production assets

= Source Code =

The source code for all compiled/minified files is included in this plugin package under js/src/.

* js/dist/qapla-pudo-block.js
  - Built from: js/src/qapla-pudo-block.js (included in this plugin)
  - Build command: npm install && npm run build

* js/google-markerclusterer.min.js
  - Library: Google Maps MarkerClusterer v2.5.3
  - License: Apache 2.0
  - Original upstream source: https://github.com/googlemaps/js-markerclusterer
  - TypeScript source included in this plugin at: js/src/google-markerclusterer/
    (files: index.ts, markerclusterer.ts, cluster.ts, renderer.ts, marker-utils.ts,
    overlay-view-safe.ts, algorithms/)

= Third Party Libraries =

* Leaflet.js (v1.9.4) - BSD 2-Clause License - https://leafletjs.com/

= CARTO Tile Service (Optional) =
* Service URL: https://basemaps.cartocdn.com
* Purpose: Alternative map tile styles (Voyager, Positron, Dark Matter) when OpenStreetMap view is configured
* Terms of Service: https://carto.com/legal/
* Privacy Policy: https://carto.com/privacy/
* Data transmitted: Map tile coordinates for rendering
* Note: Only used when user selects a CARTO tile style in plugin settings

== High-Performance Order Storage (HPOS) ==

This plugin is compatible with WooCommerce High-Performance Order Storage (HPOS).

To enable HPOS in WooCommerce:
1. Go to WooCommerce → Settings → Advanced → Features
2. Enable "High-Performance Order Storage"
3. Click "Save changes"

The plugin uses the WooCommerce Order API (`$order->get_meta()`, `$order->update_meta_data()`) for all order data operations, ensuring full compatibility with HPOS.

== Changelog ==

= 2.03 =
* Fix: REST endpoint /pudos permission_callback now verifies WordPress REST nonce (X-WP-Nonce header) instead of using __return_true — protects private API key from unauthenticated external access

= 2.02 =
* Readme: Source Code section now explicitly documents js/src/google-markerclusterer/ TypeScript sources included in the plugin package

= 2.01 =
* Fix: Tracking widget — status icon for re-entering shipments now served locally (img/status/6-2.svg) instead of cdn.qapla.it
* Fix: Plugin URL passed to tracking widget via qplpuTrackingData.pluginUrl

= 2.00 =
* Fix: REST endpoint /pudos uses __return_true permission_callback (public endpoint, no auth required)
* Fix: Rate limiting moved from permission_callback to endpoint callback
* Fix: Removed duplicate Licence header field and outdated @version docblock
* Fix: new WC_Order() replaced with wc_get_order() for HPOS compliance
* Fix: Residual get_post_meta() for tracking number replaced with $order->get_meta()
* Fix: Block editor script handle mismatch (qplpu-block → qapla-pudo-block)
* Fix: Hardcoded Italian string "Seleziona un punto di ritiro" replaced with translatable esc_attr_e()
* Fix: i18n strings for select/selected/opening_hours/phone/notes now use __() instead of locale conditionals
* Fix: Shipping method field labels translated from Italian to English (Title, Cost, Free Shipping Threshold)
* Fix: Admin instruction string for GLS API keys translated to English
* Readme: Added == Installation == section
* Readme: Added GitHub repository link for source code (issue #1 — human-readable code)
* Readme: Documented getCouriers API call with purpose and data transmitted (issue #3)
* Readme: Documented cdn.qapla.it image loading in tracking service (issue #2)
* Readme: Added missing changelog entries for versions 1.93–1.98

= 1.99 =
* Fix: PUDO data lost on order when WooCommerce refreshes checkout (updated_checkout listener)
* Fix: HPOS compatibility — replaced update_post_meta/get_post_meta with WooCommerce Order API
* Fix: Asset versioning — removed time() from wp_enqueue_style (WordPress.org guidelines)
* Fix: Admin tile preview images now served locally (no external CARTO/OSM requests)
* Fix: Updated Terms of Service and Privacy Policy URLs

= 1.98 =
* Fix: Settings link in plugin list was pointing to wrong admin page slug
* Fix: Updated Gutenberg block text domain to match plugin slug

= 1.97 =
* Fix: Admin CSS/JS not loading due to wrong page hook slug
* Fix: Removed duplicate map settings fields (now shared between Qapla and GLS tabs)
* Fix: Updated admin menu label

= 1.96 =
* Fix: Removed deprecated load_plugin_textdomain() call (WordPress 4.6+)

= 1.95 =
* Fix: Renamed plugin display name from "Qapla' Pudo v2" to "Qapla' Pudo"

= 1.94 =
* Fix: Renamed main plugin file to qapla-pudo.php to match WordPress.org slug convention

= 1.93 =
* Fix: Corrected text domain from qapla-pudo-v2 to qapla-pudo across all PHP files

= 1.92 =
* Fix geocoding for non-Italian addresses: Nominatim query now uses structured fields and countrycodes filter
* Fix distance filter zoom: reduced fitBounds padding for better map fill

= 1.91 =
* Fix zoom iniziale non adeguato al default_radius
* Fix filtri distanza OpenStreetMap non funzionanti dopo le modifiche precedenti

= 1.86 =
* Patch sicurezza

= 1.75 =
* Unified list card layout: single and multi-carrier cards now share the same 3-zone structure (header, address, carrier rows)
* Carrier logo moved from header to dedicated carrier row for clearer visual hierarchy
* Selection highlight uses box-shadow instead of border-width change (no layout shift)
* Removed obsolete CSS classes, updated tooltip positioning for unified header

= 1.74 =
* Fixed: Info tooltip now correctly reads businessHours array from API (was looking for non-existent flat fields)
* Fixed: Removed debug overlay from tooltip, restored hasInfoData gate
* Added: Info tooltip on PUDO points showing opening hours, phone, notes — hover/tap
* Added: Smart hours grouping with support for multiple daily time slots
* Changed: Font-size +2px on all popup and list elements for readability
* Changed: Info icon 22px, context-specific tooltip positioning

= 1.71 =
* Fixed: InfoWindow styling now applied via JS `domready` event — reliably overrides Google Maps inline styles
* Fixed: Close button compact circular overlay and uniform 12px padding enforced via DOM manipulation
* Changed: CSS simplified to minimal fallback (close button rules removed, handled by JS)

= 1.70 =
* Improved: Google Maps InfoWindow close button now compact circular overlay (CSS-only, superseded by v1.71)
* Improved: InfoWindow padding uniform 12px on all sides (removed extra right padding)

= 1.69 =
* Fixed: Select/Selected buttons now have uniform width (grid overlay prevents size change on toggle)
* Fixed: Preferred courier auto-select works correctly when multiple couriers share the same pickup point

= 1.68 =
* Selected PUDO Couriers: tag input with lazy-loaded autocomplete to filter map couriers (Qapla' only)
* Nearest Preferred Courier: auto-select prioritizes preferred courier at same-distance points
* New REST endpoint for fetching couriers list from Qapla' API
* API error feedback displayed under couriers field

= 1.66 =
* Reordered admin settings, removed redundant shipping method name setting
* Added shipping configuration hint with direct link

= 1.65 =
* Fixed OSM map container already initialized error
* Fixed OSM marker clustering not working

= 1.64 =
* Admin settings redesign: tab-based layout with platform tabs, card-based sections
* New OpenStreetMap Style selector with 4 tile styles and thumbnail preview cards
* New Google Maps Style selector with 6 styles and SVG-based preview cards
* Fixed OSM marker clustering race condition
* New `css/admin.css` for admin UI

= 1.54 =
* Marker clustering for both Leaflet and Google Maps
* Courier icon preloader with base64 caching
* Fixed Google Maps courier logo broken images

= 1.44 =
* List view redesign: sort by distance, group by proximity, card-based UI
* Multilingual support (IT/EN) for select buttons
* Group popup redesign on map

= 1.34 =
* Redesigned popup layout for single and group markers
* New Map Marker Style setting (pin type / courier logo)
* Courier logo markers with selection highlight

= 1.24 =
* Fixed Google Maps InfoWindow stale confirmed state
* Fixed single-marker popup missing confirmed button state

= 1.23 =
* Fixed multiple markers remaining orange after sequential confirmations
* Fixed PUDO selection freeze on single-point markers

= 1.22 =
* Fixed confirmed pin persistence when browsing other markers
* Fixed popup close restoring previous confirmed selection
* Fixed group markers orange state on click

= 1.21 =
* Fixed PUDO selection data cleared on popup close
* Fixed selected pin persistence after popup close

= 1.20 =
* Smart PUDO grouping by coordinate proximity (~50m) across all map views
* Orange selected pin on OSM map (aligned with Google Maps)
* PUDO grouping on Google Maps with numbered circle markers
* Unified group popup styling with "Confirm this pickup point" buttons
* Added CHANGELOG.md

= 1.0.0 =
* First release.
