=== BlackBoxNG Delivery for WooCommerce ===
Contributors: blackboxng, shegzico
Tags: woocommerce, shipping, lagos, delivery, courier
Requires at least: 6.2
Tested up to: 6.9
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Connect WooCommerce to BlackBoxNG for live Lagos delivery rates at checkout, automatic order dispatch, and two-way status sync.

== Description ==

**BlackBoxNG Delivery for WooCommerce** is the official WooCommerce connector for **BlackBoxNG**, a Lagos-based last-mile delivery service. The plugin itself doesn't dispatch riders or move parcels; it links your WooCommerce store to the BlackBoxNG dispatch network so that orders placed in your store automatically become delivery jobs on the BlackBoxNG side, and live shipping status flows back into the WooCommerce order as order notes and synced order statuses.

**This plugin requires an active BlackBoxNG account.** Sign up free at https://app.blackboxng.com. Without an account the shipping method won't quote rates and order sync won't fire. All delivery operations (rider dispatch, tracking, payment to BlackBoxNG for the service) happen on the BlackBoxNG side; the plugin is the connector, not the carrier.

**What you get**

* **One-paste connection.** Generate a single install token in the BlackBoxNG dashboard, paste it into WordPress, click Connect. No copy-pasting API keys, no OAuth dance.
* **Auto-configured shipping zone.** On first connect, the plugin creates a "BlackBoxNG Lagos" shipping zone wired up to our shipping method. No manual zone setup.
* **Live rate quoting at checkout.** Buyers see accurate Lagos delivery prices in real time, on both classic and block checkout. Rates are cached briefly per address so checkout stays snappy.
* **Real-time order sync.** Orders push to BlackBoxNG the moment they're placed (configurable to push on payment instead). Per-order Send / Refresh actions for manual control.
* **Two-way status sync.** When the rider picks up, departs, or delivers, the status flows back into WooCommerce as an order note plus a synced order status. No polling required; updates arrive via signed webhooks.
* **HPOS-ready.** Compatible with WooCommerce's High-Performance Order Storage (the default for new WC installs since 8.2).
* **Block-checkout compatible.** Live rates work in the Cart and Checkout blocks via WooCommerce's Store API.
* **GDPR-aware.** Personal data exporter and eraser registered with WordPress's built-in Privacy Tools so admin-initiated requests cover order data the plugin stamps locally.

**Where this plugin operates**

Lagos State, Nigeria. The shipping method only quotes rates for Lagos addresses; customers shipping elsewhere see no BlackBoxNG option at checkout and your other shipping methods handle them.

**What this plugin is NOT**

* Not a generic logistics framework: it's a connector for one specific service (BlackBoxNG).
* Not a payment processor: BlackBoxNG service charges are billed separately by BlackBoxNG, not through WooCommerce.
* Not a tracking app for end-customers: order status flows into the WooCommerce order; end-customer tracking experience is handled by your existing WooCommerce email + tracking-page setup.

== Installation ==

1. Install and activate the plugin (Plugins → Add New, or upload the .zip).
2. In WordPress admin, open the **BlackBoxNG** menu.
3. In the BlackBoxNG dashboard at https://app.blackboxng.com, generate an install token (valid for 60 minutes, single use).
4. Paste the token into WordPress and click Connect. The "BlackBoxNG Lagos" shipping zone is created automatically; new orders start syncing within seconds.

**Upgrading from a manually-distributed beta?** Deactivate the old plugin, delete it, then install this WordPress.org release. Your WooCommerce orders and zones are untouched; you reconnect once with a fresh install token from the BlackBoxNG dashboard.

== External services ==

This plugin connects to BlackBoxNG at **https://app.blackboxng.com**. Every endpoint is listed below; no data is sent to any other service.

**When you click Connect:** the plugin POSTs the install token, the WordPress site URL, and the site name to `https://app.blackboxng.com/api/woocommerce/connect`. BlackBoxNG returns a permanent API key (stored encrypted in `wp_options`) and a webhook secret for receiving status updates.

**When you click Disconnect:** the plugin POSTs to `https://app.blackboxng.com/api/woocommerce/disconnect` with the API key as a Bearer token to mark the credential row inactive on the BlackBoxNG side.

**When a customer reaches checkout:** the plugin POSTs the recipient address, weight, and total to `https://app.blackboxng.com/api/woocommerce/rate` to quote a live shipping rate. The address is used only for rate calculation; rates are cached briefly per address.

**When a new order is placed (and the BlackBoxNG shipping method was chosen):** the plugin POSTs the order details (recipient name, phone, email, shipping address, line items, total) to `https://app.blackboxng.com/api/woocommerce/orders`. This is what arranges the BlackBoxNG dispatch.

**When the rider's status changes** (picked up, in transit, delivered, cancelled): BlackBoxNG POSTs the new status to the plugin's webhook receiver at `/wp-json/blackbox/v1/status` on your site. The payload is HMAC-signed with the secret rotated at connect time.

No data is sent until you initiate one of these actions (Connect / customer-driven checkout / new order). The plugin does not phone home on install or activation.

* Terms of service: https://www.blackboxng.com/terms
* Privacy policy: https://www.blackboxng.com/privacy

== Frequently Asked Questions ==

= Do I need a BlackBoxNG account first? =

Yes. Sign up free at https://app.blackboxng.com. The plugin is a connector for the BlackBoxNG dispatch service; without an account, no rates are quoted and no orders are dispatched.

= Where is my data stored? =

The plugin stores your BlackBoxNG API key encrypted in WordPress's `wp_options` table (AES-256-GCM, keyed off your site's `AUTH_KEY`). Order data flows through the BlackBoxNG API; see https://www.blackboxng.com/privacy for retention details on the BlackBoxNG side. The plugin stamps a tracking identifier on each WooCommerce order it dispatches; nothing else customer-identifiable is stored locally.

= What happens at checkout if my customer's address is outside Lagos? =

The BlackBoxNG shipping option won't appear: the API returns no rate for out-of-zone addresses, and WooCommerce naturally falls back to your other configured shipping methods.

= How do I disconnect? =

Open WordPress → BlackBoxNG → Disconnect. The plugin POSTs a disconnect signal to BlackBoxNG, then wipes the local API key. You can reconnect later by generating a fresh install token.

= Will this work with my existing shipping methods? =

Yes. The plugin adds a new "BlackBoxNG Lagos" shipping zone; your existing zones and methods are untouched. WooCommerce shows BlackBoxNG delivery to customers shipping into Lagos and your other methods to customers elsewhere.

= Does the plugin send any data on install or activation? =

No. The activation hook only sets a one-time welcome-notice transient. No remote calls happen until you click Connect; no data is sent to BlackBoxNG, no tracking pixels, no analytics, no "phone home" of any kind.

= How much does this cost? =

The plugin is free. BlackBoxNG charges per delivery based on distance, weight, and tier; pricing is shown in the BlackBoxNG dashboard and at checkout (the rate the customer sees). See https://www.blackboxng.com for current pricing.

= Where can I get help? =

Open a thread in the WordPress.org support forum for this plugin, or contact BlackBoxNG support directly from https://app.blackboxng.com for issues that need account-side investigation.

= Does this support High-Performance Order Storage (HPOS) and the block-based checkout? =

Yes to both. The plugin declares compatibility with `custom_order_tables` (HPOS) and `cart_checkout_blocks`. Order meta is read and written via WooCommerce's order API rather than `wp_postmeta`, and shipping rates are exposed to the Store API consumed by the Cart/Checkout blocks.

= How are personal data export and erasure requests handled? =

The plugin registers WordPress's built-in privacy exporter and eraser. When an admin uses Tools → Export Personal Data or Tools → Erase Personal Data with a customer email, the plugin returns / removes any BlackBoxNG tracking identifiers stamped on that customer's orders. Erasing the customer's record on the BlackBoxNG side is a separate request you make directly to BlackBoxNG via https://www.blackboxng.com/privacy.

== Screenshots ==

1. WordPress plugins list with the BlackBoxNG Settings link.
2. The connect screen: paste your install token, click Connect.
3. The auto-configured "BlackBoxNG Lagos" shipping zone.
4. Live rate quoting at the WooCommerce checkout.
5. The per-order BlackBoxNG panel with tracking ID and a Refresh button.
6. The order list with the BlackBoxNG sync status column.

== Changelog ==

= 1.0.0 =
* Initial WordPress.org release.
* Install-token connect flow (no API key copy-pasting).
* Auto-configured Lagos shipping zone.
* Real-time order push (configurable: on creation or on payment).
* Live rate quoting at checkout, classic and block.
* Two-way status sync via signed webhooks (no polling required).
* HPOS + Cart/Checkout Blocks compatibility declarations.
* WordPress Privacy Tools integration (exporter + eraser + policy suggestion).

== Upgrade Notice ==

= 1.0.0 =
First WordPress.org release.
