=== Quick Stock Bridge ===
Contributors: neutropeinc
Tags: woocommerce, amazon, stock, inventory, csv
Requires at least: 6.0
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 0.2.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Build Amazon stock-update CSV/JSON files from WooCommerce inventory. Manual and dry-run focused: it never sends anything to Amazon.

== Description ==

Quick Stock Bridge helps WooCommerce store operators prepare Amazon stock-update files from their existing WooCommerce inventory, safely and on their own terms.

It is intentionally a **manual, dry-run** tool. It does not connect to the Amazon SP-API, it does not send any data to Amazon, and it never writes to WooCommerce product data. You stay in full control: review the preview, download a CSV or JSON file, and upload it to Amazon yourself.

= What it does =

* Reads WooCommerce products and variations (simple and variable products).
* Lets you map each product/variation to an Amazon SKU and ASIN.
* Calculates the quantity to report to Amazon from your stock rules.
* Resolves the quantity from a configurable stock source: WooCommerce stock, or an external stock value you import, with an optional fallback.
* Previews every row with a clear OK / Warning / Error / Skipped status.
* Exports CSV or JSON with a stable column set (including external_stock_quantity and stock_source).
* Records an export log (summary plus a per-item snapshot).

= New in 0.2.0 =

* **External stock value** (`external_stock_quantity`): keep an Amazon-facing quantity per mapping, independent of WooCommerce stock.
* **Stock source** (`stock_source`): choose WooCommerce or external stock as the primary source, with an optional fallback to the other.
* **Mapping CSV export / import**: download every product/variation merged with its mapping, edit it in a spreadsheet, and re-import it.
* **Dry-run preview -> apply** for imports: every import shows exactly what would change (create / update / unchanged / skip / warning / error) and writes nothing until you confirm.
* **ASIN auto-fill**: extract ASINs from a product/variation custom field (an Amazon product URL or a bare ASIN) and fill blank ASINs, again with a preview before anything is written. Existing ASINs are never overwritten.

Every write is opt-in and preview-gated, and the plugin still never contacts Amazon and never edits your WooCommerce products.

= Stock calculation =

For each mapping, the export quantity is resolved in this order:

1. If sync is disabled for the item, it is excluded.
2. The stock source is resolved (WooCommerce stock or the imported external value, per your settings, with optional fallback).
3. If no stock source is available, the item is excluded or flagged with a warning (your choice).
4. If the Amazon SKU is missing, the item is reported as an error.
5. If a manual override is set, that value is used.
6. Otherwise the quantity is the resolved source stock minus safety stock.
7. A max-stock cap is applied if configured.
8. Negative results are clamped to 0.

With the default settings (primary source = WooCommerce, no external stock imported) the calculation behaves exactly as in 0.1.x.

= Not included in 0.2.0 =

* Sending data to the Amazon SP-API.
* Importing Amazon orders or FBA stock.
* Automatic / scheduled synchronization.
* Writing to WooCommerce product or stock data.
* Rakuten, Yahoo!, or Shopify integration.

This plugin is a generic WooCommerce tool. It is not tied to any specific store, product naming scheme, or SKU format.

== Installation ==

1. Upload the `quick-stock-bridge` folder to `/wp-content/plugins/`, or install the ZIP from Plugins → Add New.
2. Activate the plugin through the Plugins screen.
3. Make sure WooCommerce is installed and active.
4. Open **Stock Bridge** in the admin menu and start with Product Mappings.

== Frequently Asked Questions ==

= Does this send stock to Amazon automatically? =

No. Version 0.1 only builds files for you to download and upload manually. Nothing is sent to Amazon.

= Does it change my WooCommerce stock? =

No. The plugin only reads WooCommerce stock. It never writes to it.

= What happens if WooCommerce is not active? =

The plugin runs in a limited, read-only state and shows a warning. Product reading and exports are disabled until WooCommerce is active.

= Where is my data stored? =

Mappings and export logs are stored in custom database tables. You can opt in (Settings → On uninstall) to delete all plugin data when the plugin is removed.

= What is "external stock" and how is it different from WooCommerce stock? =

External stock is an optional quantity you store per mapping (for example an Amazon-facing figure that differs from your WooCommerce shop stock). You import it via the mapping CSV. In Stock Rules you choose which source is primary (WooCommerce or external) and whether to fall back to the other when the primary is unavailable. By default WooCommerce stock is used, so nothing changes unless you opt in.

= Will importing a CSV change my products? =

No. The mapping CSV import only updates the plugin's own mapping table, and only after you review the dry-run preview and press Apply. It never edits WooCommerce products, prices, or stock.

= How does ASIN auto-fill work? =

You point it at a product/variation custom field (post meta) that holds an Amazon product URL or a bare ASIN — for example product_amazon_url. The plugin extracts the ASIN, previews the candidates, and on apply fills only blank ASINs. Existing ASINs are never overwritten, variations fall back to the parent product's field, and no data is sent to Amazon.

== Screenshots ==

1. Dashboard: WooCommerce status, mapping and sync counts, and recent exports.
2. Product Mappings: map each product/variation to an Amazon SKU and ASIN, with per-item safety stock, max stock, manual override, and sync.
3. Stock Rules: default safety and max stock, plus the stock source (WooCommerce or external) with an optional fallback.
4. Settings: CSV/JSON format options and the ASIN auto-fill source meta key.
5. Import / Export: mapping CSV export and a dry-run import preview (create / update / unchanged / skip / warning / error) that writes nothing until you apply.
6. ASIN Auto Fill: preview of ASINs extracted from a product custom field; only blank ASINs are filled and existing ones are never overwritten.
7. Amazon Export preview: per-row OK / Warning / Error / Skipped with calculated stock, stock source, and external stock, plus CSV / JSON download.
8. Logs: export history with per-item snapshots.

== Changelog ==

= 0.2.2 =
* Internal: renamed the plugin's global prefix to a longer, more unique prefix (QSTBR_ / qstbr_) to follow WordPress.org guidelines. This affects constants, class names, option names, hooks, transients, nonces, custom database table names, and asset handles.
* No user-facing feature changes. The text domain and plugin slug remain "quick-stock-bridge".
* Note: internal option and table names changed and are not migrated from earlier 0.2.x development builds; the plugin starts with fresh data on this version.

= 0.2.1 =
* Pre-submission cleanup: corrected the plugin header description (it no longer references "v0.1"); it now states that the plugin never sends data to Amazon and never changes WooCommerce product data.
* No functional changes; behavior is identical to 0.2.0.

= 0.2.0 =
* Stock source: choose WooCommerce or an external stock value as the primary source, with an optional fallback (Settings -> Stock Rules). Default is WooCommerce, so existing behavior is unchanged.
* External stock value (external_stock_quantity) stored per mapping and usable as the Amazon-facing quantity.
* Amazon Export: added external_stock_quantity and stock_source columns to the CSV/JSON output and the preview.
* Mapping CSV export/import: download all products/variations merged with their mapping, edit in a spreadsheet, and re-import.
* Import is dry-run first: a preview shows create / update / unchanged / skip / warning / error per row and writes nothing until you apply.
* ASIN auto-fill: extract ASINs from a configurable product/variation custom field (Amazon URL or bare ASIN) and fill blank ASINs after a preview. Existing ASINs are never overwritten; variations fall back to the parent product's field.
* Still manual and dry-run: no Amazon SP-API calls, and WooCommerce product/stock data is never modified.

= 0.1.1 =
* Dashboard: added a "Not stock-managed" product count and a notice explaining that those items are excluded from the export by default.
* Amazon Export: the preview now shows how many items were skipped because WooCommerce stock management is off, with guidance on how to include them.
* Product Mappings: clarified that ASIN is optional, that only the current page is saved, and what a "not managed" stock value means.
* No changes to the stock-calculation logic or the CSV/JSON output format.

= 0.1.0 =
* Initial release: product mappings, stock rules, preview, CSV/JSON export, and export logs. Manual / dry-run only — no Amazon API.

== Upgrade Notice ==

= 0.2.2 =
Internal global-prefix change for WordPress.org compliance (QSTBR_ / qstbr_). No feature changes. Internal option and table names changed and are not migrated from earlier 0.2.x development builds.

= 0.2.1 =
Documentation/metadata cleanup before WordPress.org submission (plugin header description fix). No functional changes from 0.2.0.

= 0.2.0 =
Adds external stock values, a configurable stock source, mapping CSV import/export with dry-run preview, and ASIN auto-fill. The database is upgraded automatically (new columns only; existing data is preserved). Defaults keep the 0.1.x behavior. Still no Amazon API and no writes to WooCommerce data.

= 0.1.1 =
UI clarity improvements for stores that do not use WooCommerce stock management. No data or output format changes.

= 0.1.0 =
Initial release.
