=== PrintaRex Integration for WooCommerce ===
Contributors: ibrahimsiam
Tags: shipping, woocommerce, printarex, zone-based, real-time rates
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 8.0
WC requires at least: 8.0
WC tested up to: 11.2
Stable tag: 1.1.5
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Real-time zone-based shipping rates from PrintaRex for WooCommerce stores.

== Description ==

PrintaRex Integration for WooCommerce connects your store to the PrintaRex fulfillment network, providing accurate per-city, per-item shipping rates at checkout.

**Key Features:**

* **Real-time rates** - Shipping costs are calculated based on the customer's exact city, not just country or state.
* **Per-item pricing** - Each product is priced individually based on its provider's shipping zones.
* **Zero-configuration setup** - Connect your store to PrintaRex, install the plugin, done. The connection, signing secret, and shipping zone are configured automatically. If you already have a shipping zone for your country, PrintaRex Shipping is added to it so your other shipping methods keep working.
* **Self-healing connection** - If you delete and reconnect your store in PrintaRex, the plugin picks up the new connection by itself. No reinstalling needed.
* **Mixed cart support** - Non-PrintaRex items are silently ignored; they use your existing WooCommerce shipping zones. In a shared zone the PrintaRex rate appears alongside your own methods.
* **Fallback rate** - If the PrintaRex API is temporarily unavailable, a configurable flat rate is used.
* **Caching** - Rates are cached for 5 minutes (configurable) to minimize API calls.
* **PrintaRex admin page** - A dedicated PrintaRex menu in WordPress lets you connect your store, review your setup status, and open your PrintaRex dashboard without leaving WordPress.

**Supported Countries:**

The plugin provides per-city zone rates for all countries in the PrintaRex network, including UAE and Egypt - even for countries where WooCommerce has no built-in state/province definitions.

== Installation ==

1. Connect your store to PrintaRex (PrintaRex Dashboard > Stores > Add Store > WooCommerce).
2. In your WordPress admin, go to **Plugins > Add New**, search for **PrintaRex Integration for WooCommerce**, click **Install Now**, then **Activate**.
3. That's it. The plugin configures itself: it finds your store's PrintaRex connection, sets up signed rate requests, and adds PrintaRex Shipping to your shipping zones automatically.

**Verify the setup:**

1. Go to **WooCommerce > Settings > Shipping > PrintaRex Shipping**.
2. Confirm that the **Store Connection ID** field is populated.
3. If it is empty, make sure your store is connected to PrintaRex, then click **Save changes** on this screen to retry.

== Frequently Asked Questions ==

= Does this plugin require a PrintaRex account? =

Yes. You must have an active PrintaRex merchant account with a connected WooCommerce store. The plugin communicates with the PrintaRex API to fetch shipping rates for your products.

= What happens if the PrintaRex API is down? =

The plugin uses a configurable fallback rate (default: 30 in your store currency) so customers can still complete checkout.

= What happens if I disconnect my store from PrintaRex? =

Once the plugin confirms PrintaRex no longer has your store, it hides its flat fallback rate whenever your own shipping methods offer a rate for the cart, so customers only see your methods. If nothing else is available, the fallback rate stays so checkout still works. Reconnect your store and rates resume automatically.

= Does this work with variable products? =

Yes. The plugin sends the WooCommerce variation ID for variable products, which maps to the correct PrintaRex product variant.

= Can I use this alongside other shipping methods? =

Yes. PrintaRex Shipping only calculates rates for products fulfilled through PrintaRex. Other products in the cart will use your existing WooCommerce shipping zones and methods. If you already have a shipping zone for your country, PrintaRex Shipping is added to that zone and appears next to your own methods, so customers may choose the cheaper of your rate and the PrintaRex rate. Remove either method from the zone if you only want one of them offered.

= How do I change the API URL for development? =

Go to WooCommerce > Settings > Shipping > PrintaRex Shipping and update the API URL field.

== Screenshots ==

1. PrintaRex Shipping settings page in WooCommerce (WooCommerce > Settings > Shipping > PrintaRex Shipping).
2. Real-time shipping rate displayed at checkout, calculated per customer city.
3. Auto-configured store connection after plugin activation.

== External Services ==

This plugin connects to the **PrintaRex API** (`https://api.printarex.com` by default; configurable in the plugin settings) to provide real-time shipping rates. Requests are made in the following scenarios:

* **Plugin activation & admin auto-configuration** — A GET request is sent to `{api_url}/carrier-service/woocommerce/lookup` with your site domain to retrieve your store connection ID. This runs on activation, when you open the PrintaRex admin page, and is retried periodically from the WordPress admin if the connection ID is missing (with a 1-hour backoff between attempts). If PrintaRex rejects a rate request, the same lookup is repeated once in the background (at most every 15 minutes) to pick up a changed connection ID; it never delays checkout. Rate requests are signed with the WooCommerce REST API consumer secret that your own store created when connecting to PrintaRex — the plugin reads it locally from your WordPress database and never transmits it.
* **Background re-checks** — The same lookup is also sent without anyone opening the admin page in three cases: about a minute after the `PrintaRex — …` shipping zone the plugin placed its method in, or is waiting on, is deleted (for example when you switch to per-zone rates or disconnect; deleting one of your own zones triggers nothing); every hour while PrintaRex reports the store as not connected (or cannot be reached) and that zone is gone or still pending, which also continues after the plugin is deactivated and reactivated; and, while the store is flagged as not connected, at most every 15 minutes in the background after a checkout rate calculation. It never delays checkout.
* **Checkout rate calculation** — A POST request is sent to `{api_url}/carrier-service/woocommerce/{connectionId}/rates` each time a customer enters their shipping address at checkout.

**Data transmitted to PrintaRex:**

* Your store's domain (during every lookup: activation, the admin page, and the background re-checks listed above)
* Customer destination city and country code (during rate calculation)
* Cart item WooCommerce product/variation IDs and quantities
* Store currency code

**No personal customer data** (name, email, phone, payment details, IP address) is transmitted.

* [PrintaRex Website](https://printarex.com)
* [PrintaRex Terms of Service](https://printarex.com/terms)
* [PrintaRex Privacy Policy](https://printarex.com/privacy)

== Changelog ==

= 1.1.5 =
* Fixed shipping falling back to the flat fallback rate after you delete and reconnect your store in PrintaRex. The plugin now picks up the new connection by itself: right away when you open the PrintaRex page if no shipping zone has the method, otherwise in the background after the first rejected rate request.
* The PrintaRex admin page now shows a "Paused" status when PrintaRex cannot reach your store. While paused, new orders are not received; it resumes automatically once your store is reachable. The page explains what to check (your site, security plugin, firewall).
* When the plugin sets itself up, PrintaRex Shipping is now added to the shipping zone you already have for your store's country instead of a new zone that hides your other shipping methods. A dedicated PrintaRex zone is only created when no zone covers your country and your "Locations not covered by your other zones" zone has no methods of its own, and it is placed after your existing zones. Zones created by earlier versions are left as they are.
* If your PrintaRex shipping zone is deleted when you disconnect and you reconnect, PrintaRex Shipping is placed again automatically within about an hour, or right away when you open the PrintaRex page in WordPress. Stores updated from 1.1.4 are covered once the plugin has checked the store at least once before the disconnect (by opening the PrintaRex page or a background check). If you removed the method from a zone yourself, it stays removed. Deleting the PrintaRex zone itself puts PrintaRex Shipping back, so to stop using it remove the method from the zone instead (or deactivate the plugin).
* If your store is no longer connected to PrintaRex, the plugin hides its flat fallback rate whenever your own shipping methods offer a rate for the cart. If nothing else is available, the fallback rate stays so checkout is never left without a shipping option.
* Removing the plugin now also removes PrintaRex Shipping from your shipping zones.
* Rate requests now use the key created when you connected your store to PrintaRex, rather than any key whose name starts with "PrintaRex".
* Dashboard and Connect links now follow the PrintaRex environment your store is connected to.
* The Status tab now warns when your PHP version is end-of-life or is missing the security update released on 21 October 2026, so you can ask your host to update PHP. It is only a notice and does not affect your connection or checkout. On hosts that backport security fixes the notice is worded as a possibility, since the version number alone cannot show whether the fix is present.
* Tested with WordPress 7.1 and WooCommerce 11.2.

= 1.1.4 =
* Added a Disconnect store button to the Connect tab — it opens your store's page on PrintaRex, where the disconnect is confirmed with your PrintaRex login.

= 1.1.3 =
* The Connect tab now shows your connection details once the store is linked, instead of the connect call-to-action.

= 1.1.2 =
* The PrintaRex admin page now completes an unfinished setup automatically: if your store is connected to PrintaRex but the plugin's local configuration is missing (for example when the store was connected after the plugin was activated), opening the page stores the connection and creates the shipping zone by itself.

= 1.1.1 =
* The admin menu now uses the PrintaRex logo.

= 1.1.0 =
* New PrintaRex admin page in WordPress: connect your store, check setup status, and jump to your PrintaRex dashboard without leaving WordPress.

= 1.0.7 =
* Zero-configuration setup: the API URL now defaults to the production PrintaRex API, and the signing secret is discovered automatically from the WooCommerce REST API key created when your store was connected to PrintaRex. No manual configuration needed.

= 1.0.6 =
* Saving the shipping settings now retries auto-configuration immediately — previously the hourly backoff could delay the first connection lookup after entering the API URL.
* Installation instructions rewritten for installs from the WordPress.org plugin directory.

= 1.0.5 =
* Renamed plugin to PrintaRex Integration for WooCommerce.
* Updated text domain to printarex-integration-for-woocommerce to match the requested new slug.

= 1.0.4 =
* Updated WordPress tested-up-to version to 7.0 and WooCommerce tested-up-to version to 10.9.
* Rate requests are now always HMAC-signed using the WooCommerce consumer secret configured in the shipping method settings; if no secret is configured the fallback rate is used instead of sending an unsigned request.
* The API secret is no longer stored from the lookup response — it is entered by the merchant in the shipping method settings.

= 1.0.3 =
* Renamed plugin display title to PrintaRex Shipping for WooCommerce for clearer discoverability.
* Added Requires Plugins header for WooCommerce dependency.
* Updated WordPress tested-up-to version to 6.9.

= 1.0.2 =
* Fixed contributor username in readme.
* Fixed license header format inconsistency.
* Updated tested-up-to versions.
* Removed hardcoded API URL fallback — plugin returns early if no URL configured.

= 1.0.1 =
* Added uninstall.php for clean option and transient removal.
* Added External Services disclosure for WordPress.org compliance.
* Fixed malformed API response handling — invalid JSON now triggers fallback rate.
* Fixed multi-currency cache key — currency is now included in rate cache.
* Fixed auto-configuration retry loop — 1-hour backoff between failed attempts.
* Fixed double URL encoding in domain lookup.
* Fixed multisite WooCommerce detection (network-activated support).
* Fixed zone creation when store base country is not configured.
* Fixed WPCS escaping in admin notice output.
* Updated readme accuracy (external services disclosure, feature descriptions).

= 1.0.0 =
* Initial release.
* Real-time zone-based shipping rate calculation.
* Zero-config auto-setup via domain lookup.
* Transient-based rate caching.
* HMAC-SHA256 request signing for API security.
* Configurable fallback rate, request timeout, and cache duration.
* WooCommerce HPOS compatibility.

== Upgrade Notice ==

= 1.1.5 =
Recommended. Fixes shipping rates falling back to the flat rate after a store is reconnected in PrintaRex and adds a Paused status. New setups use your existing shipping zone instead of adding one that hides your other shipping methods; zones from earlier versions are not changed.
