﻿=== Packing Station for WooCommerce ===
Contributors: ateqa
Tags: woocommerce, packing, orders, printing, order management
Requires at least: 5.8
Tested up to: 7.0
Requires PHP: 7.4
Requires Plugins: woocommerce
Stable tag: 1.0.0
License: GPL-2.0-or-later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Packing station interface for WooCommerce: live order feed, configurable modal, automatic field discovery, and optional stock and order control.

== Description ==

[Documentation](https://ateqa.com/packing-station-plugin/) | [Companion Print App](https://ateqa.com/) | [Developer Hooks](https://ateqa.com/packing-station-developer-hooks/)

Packing Station for WooCommerce gives your fulfilment team a clean, purpose-built order workspace separate from wp-admin. Staff log in through a dedicated Packing Station page and manage incoming WooCommerce orders from a focused screen built for kitchens, packing benches, counters, and fulfilment stations.

The plugin works in a normal browser without the Android app. The optional [Packing Station Print App](https://ateqa.com/) is the companion upgrade path when you want local Android-connected printing, print buttons, reprints, labels, and optional auto-printing for new orders.

**Who is Packing Station for?**

* **Hotel kitchen** — incoming room service and restaurant orders placed through an online menu, with the room number and any special requests shown directly on the order card.
* **Restaurant or café** — a clean order screen for website or QR-code orders, visible to kitchen staff without any wp-admin access.
* **Bakery, meal prep, or delivery kitchen** — a live production screen for orders that need to be prepared, packed, labelled, or collected.
* **Flower shop or florist** — pick, pack, and mark online orders complete for delivery or collection, all from a single screen.
* **Dark kitchen or delivery operation** — a dedicated order processing display that keeps fulfilment staff away from the main admin.
* **Local retail or speciality store** — a simple order handling screen for teams packing physical WooCommerce orders.
* **Any WooCommerce store** — a purpose-built fulfilment station for any operation that processes physical orders and wants to keep staff out of wp-admin.

**Order Feed**

Live auto-refreshing order feed showing compact cards (order number, status, date/time, customer, item summary, and optional total) with a browser chime for new orders. Filters by date range and order status. Each card has View and Complete buttons. A dark mode toggle in the header lets staff switch between light and dark colour schemes; the preference is saved per browser.

**Order Detail Modal**

Full-screen modal showing the complete order in labelled sections: core details, line items, totals, customer, billing/shipping addresses, and any additional fields from other plugins.

**Configurable Fields**

Go to **WooCommerce → Packing Station** to choose which fields appear in the modal. Three ways to add fields:

1. **Built-in fields** — 35+ fields across seven groups (Core Order, Line Items, Totals, Customer, Billing, Shipping, Other). Line item name/qty and item price are separate toggles so you can show quantities without prices, or include both.
2. **Discovered third-party fields** — The plugin scans recent orders for extra meta fields from other plugins (room numbers, table references, custom checkout fields) and lists them with sample values.
3. **Custom meta keys** — Manually enter any `meta_key` for fields not yet discovered.

Click **Re-scan Orders** at any time to refresh discovered fields. Discovery also runs automatically on first activation.

**Optional Pages (disabled by default)**

* **Order Control** — Lets staff instantly pause all incoming WooCommerce orders in an emergency. Classic checkout and WooCommerce Cart/Checkout Blocks are blocked site-wide until resumed. Enable only if you want packing station staff to have this capability.
* **Stock Control** — Searchable, paginated product list with a one-tap in-stock/out-of-stock toggle, without needing wp-admin access.

Enable either page in the **Features** section at the bottom of **WooCommerce → Packing Station**.

**Android Printing**

The WordPress plugin is fully functional without the Android app. The companion app is optional and only adds local printing.

When the order feed is opened inside the [Packing Station companion app](https://ateqa.com) on Android, the plugin automatically detects the printing bridge and enables Print buttons on every order card and inside the Order Detail modal. No plugin configuration, API keys, or pairing is needed — the buttons simply appear.

When running in a standard browser (without the companion app), staff open the browser login URL shown at the top of **WooCommerce → Packing Station**. This is your site root URL plus `/packing-station-login/`. Staff log in with a user assigned the **Packing Station** role, then they are taken to the Packing Station order feed. The Print buttons are hidden and a download hint is shown in their place. Everything else — the order feed, View modal, Complete button, filters, and all admin settings — works the same in both environments.

Install the companion app on any Android device with an attached printer: a tablet connected to a desktop or label printer, or a POS device with an integrated thermal printer. Auto-printing of new orders on arrival is also supported.

In the Android app settings, enter the site root URL shown at the top of **WooCommerce → Packing Station**. The app uses this root URL to find the Packing Station login page. Staff then log in with the same **Packing Station** role user account and are taken to the order feed.

Print a **packing list** to include inside the package (ideal for retail fulfilment or restaurant room service orders), or print a **shipping label** to stick on the outside. Works with thermal receipt printers, label printers, and standard desktop printers.

The companion app includes **100 free prints** so you can fully test your printing setup before committing to a purchase. The app is free to download; a subscription or print pack is required once the free allowance is used. This print allowance applies only to the optional Android app and does not limit the WordPress plugin.

**Other Features**

* Connection indicator, browser audio chime for new orders (can be disabled from the Features panel), dark mode toggle, custom "Packing Station" user role, login gate, standalone page template, HPOS compatibility.
* Responsive interface — works on desktop, laptop, tablet, and mobile browsers.
* Developer hooks for controlled extension of the order feed, print payload, field registry, access checks, stock updates, order status updates, and emergency order pause/resume events.

**Developer Extensibility**

The plugin includes a starter set of WordPress actions and filters for store developers who need to adapt the Packing Station workflow without forking the plugin. Hooks are available for order feed queries, prepared order data, selectable print fields, the Android print payload, access checks, order status changes, stock status changes, and order control changes.

The print payload hooks are guarded: after custom code runs, the plugin restores the minimum core keys the Android companion app expects where possible. See the [Developer Hooks documentation](https://ateqa.com/packing-station-developer-hooks/) for the full hook reference and examples.

**Pages Created on Activation**

* `/packing-station-order-feed/` — Order feed
* `/packing-station-login/` — Staff login
* `/packing-station-store-open-close/` — Order Control (optional, disabled by default)
* `/packing-station-stock-control/` — Stock Control (optional, disabled by default)

== Installation ==

Install from the WordPress plugin directory:

1. Go to **Plugins → Add New Plugin**.
2. Search for **Packing Station for WooCommerce**.
3. Click **Install Now**.
4. Click **Activate Plugin**.

Or install a zip file downloaded from ateqa.com:

1. Go to **Plugins → Add New Plugin**, click **Upload Plugin**, select the zip file, and click **Install Now**.
2. Click **Activate Plugin**.

After activation:

1. Go to **Users → Add New User** and create a dedicated staff account, for example **Packer**.
2. Set the new user's role to **Packing Station**. Do not change an existing administrator or shop manager account to this role, because the standard WordPress role dropdown replaces that user's current role.
3. Go to **WooCommerce → Packing Station** and tick the fields you want in the Order Detail modal.
4. Click **Re-scan Orders** to discover fields added by other plugins.
5. Enable **Order Control** and/or **Stock Control** in the Features section if needed.
6. Click **Save Changes**.

For normal browser access, give staff the browser login URL shown at the top of **WooCommerce → Packing Station**. This is your site root URL plus `/packing-station-login/`. Staff log in with the **Packing Station** role user account created above, then they are taken to the Packing Station order feed.

For Android app access, enter the site root URL shown at the top of **WooCommerce → Packing Station** in the app settings. The app uses this to find the Packing Station login page; staff still log in with the same **Packing Station** role user account.

== Frequently Asked Questions ==

= What user role is needed to access the packing station? =

The **Packing Station** custom role (created automatically on activation) or **Administrator**. All other users are redirected to the login page.

= How do I add staff members? =

Go to **Users → Add New User** and create a dedicated staff account, for example **Packer**. Set that new user's role to **Packing Station**. Avoid changing an existing administrator or shop manager account to this role in the WordPress admin screens, because the role dropdown replaces the user's current role.

= Does this plugin work with WooCommerce HPOS? =

Yes, full compatibility with WooCommerce High-Performance Order Storage is declared.

= How do I choose which fields appear in the Order Detail modal? =

Go to **WooCommerce → Packing Station** and tick fields in the built-in groups, enable discovered third-party fields, or add custom meta keys manually. Click **Save Changes**.

= What is automatic field discovery? =

Clicking **Re-scan Orders** scans your most recent orders for meta fields added by other plugins and lists them as checkboxes with sample values. Discovery also runs on first activation.

= How do I enable the Order Control or Stock Control page? =

Go to **WooCommerce → Packing Station**, scroll to the **Features** section, check the toggle for the page you want, and click **Save Changes**.

= Can I disable the audio chime for new orders? =

Yes. Go to **WooCommerce → Packing Station**, scroll to the **Features** section, and uncheck **New Order Sound**. This is useful when running the Android companion app (which has its own audio alert) or in a silent display environment. The native Android sound is unaffected by this setting.

= Does the interface have a dark mode? =

Yes. Click the 🌙 icon in the header bar to switch to dark mode. The preference is saved in your browser and persists across page loads and sessions. Each device or browser can have its own preference.

= What does the Order Control page do? =

Gives packing station staff a screen to immediately pause all incoming WooCommerce orders in an emergency (power cut, staffing crisis, etc.). Classic checkout and WooCommerce Cart/Checkout Blocks are blocked site-wide until staff resume it from the same screen.

= What does the Stock Control page do? =

Provides a searchable product list where staff can toggle items in/out of stock with a single tap, without needing wp-admin access.

= How do Print buttons appear? =

The plugin detects whether it is running inside the Packing Station companion app on Android. If the companion app's printing bridge is present, Print buttons are automatically shown on every order card and inside the Order Detail modal. No plugin configuration or pairing is needed. When accessed from a standard browser, the Print buttons are hidden and a companion app download hint is shown instead.

= Is the Android app required? =

No. The WordPress plugin works fully in a standard browser without the Android app. The companion app is optional and only adds local printing from Android devices with an attached or integrated printer. The app's free print allowance, subscription, or print pack does not limit use of the WordPress plugin.

= How does printing work? =

Install the free [Packing Station companion app](https://ateqa.com) on any Android device with an attached printer — a tablet connected to a desktop or label printer, or a POS device with an integrated thermal printer. When the order feed is opened inside the companion app, Print buttons appear automatically. Auto-printing of new orders is also supported.

Print a **packing list** to include inside the package (ideal for retail fulfilment or restaurant room service orders), or print a **shipping label** to stick on the outside. Works with thermal receipt printers, label printers, and standard desktop printers. The companion app is free to download and includes **100 free prints** so you can fully test your setup before committing to a purchase. A subscription or print pack is required once the free allowance is used in the Android app.

= Does it work on different types of Android devices? =

Yes, the interface is optimised for POS devices with integrated thermal pronters or tablets mounted at a packing or fulfilment station and works on desktop and mobile browsers too.

= What happens when I deactivate the plugin? =

Rewrite rules are flushed; all data and pages remain intact so you can reactivate without losing your configuration.

= What happens when I delete the plugin? =

When the plugin is deleted from the WordPress admin, its uninstall cleanup removes the four Packing Station pages, the custom **Packing Station** role, and the plugin options `psfw_store_closed`, `psfw_print_fields`, `psfw_print_custom_meta`, `psfw_discovered_meta`, and `psfw_features`.

If the plugin files are removed manually by FTP or file manager instead of using **Plugins → Delete**, WordPress does not run the uninstall cleanup.

== Screenshots ==

1. Order feed — live auto-refreshing cards showing order number, status, date/time, customer, item summary, and total.
2. Order Detail modal — full order breakdown in labelled sections, opened from the View button on any order card.
3. Admin settings page — choose which order fields appear in the Order Detail modal and companion app print payload.
4. Admin settings page — run field discovery, add custom meta keys, and enable optional Order Control, Stock Control, and new order sound features.
5. Stock Control page — searchable product list with one-tap in-stock/out-of-stock toggle.
6. Order Control page — dedicated screen to instantly pause or resume all incoming WooCommerce orders.
7. Packing Station navigation — slide-out menu showing the order feed, optional Order Control, Stock Control, filters, and logout link available to packing staff.

== Changelog ==

= 1.0.0 =
* Initial release.
* Live order feed with 15-second auto-refresh, date/status filters, and compact order cards showing order number, status, date/time, customer, item summary, and optional line-item price.
* Order Detail modal — full-detail view with configurable grouped sections (Core, Items, Totals, Customer, Billing, Shipping, Other, Additional Fields).
* 35+ built-in order fields across seven groups. Line item name/qty and item price are independent toggles.
* Automatic third-party field discovery — scans recent orders for meta fields added by other plugins; Re-scan Orders AJAX button refreshes at any time.
* Discovered fields panel shows a Field Key / Sample Value column header for easy identification.
* `_sections` structured array in REST API response for Android companion app receipt layouts.
* Developer hooks for order feed query customisation, print payload extension, field registry extension, access checks, and post-update actions.
* Order Control page — instantly pause/resume all incoming WooCommerce orders; disabled by default.
* Stock Control page — searchable, paginated product list with one-tap in-stock/out-of-stock toggle; disabled by default.
* New Order Sound feature flag — enable/disable the browser audio chime from the Features section independently of the Android companion app audio.
* Browser audio chime (Web Audio API) for new orders when running outside the companion app.
* Dark mode — 🌙/☀️ toggle in the header bar; preference saved per browser via localStorage.
* Android printing via the [Packing Station companion app](https://ateqa.com); Print and auto-print buttons appear automatically when the order feed is opened inside the companion app.
* Custom Packing Station user role with minimal WooCommerce capabilities and dedicated login page.
* Standalone full-width page template with slide-out sidebar navigation.
* HPOS compatibility declared.
