# 🔨 Factorize Auctions

> Weekly auctions that run themselves, one unit at a time.
>
> **Suite identity:** icon 🔨 · accent `#c8552d` · part of the [Factorize suite](../README-FACTORIZE.md)

## What it does

Runs the store's auction lifecycle on top of the Ultimate Auction for WooCommerce plugin. Every auction sells one unit per weekly cycle: an hourly tick relists failed cycles (and cycles whose winner ghosted past the grace window), and a paid order — Buy Now or winning bid — either relists the next unit or ends the auction for good. On the storefront it adds the billing-details bid gate, the grayed-out Buy Now button once bidding passes the price, a one-tap quick-bid button, card extras (Buy Now line, retail-discount %, ends-soon badge), the "X% below retail" line, per-product returns modes, the inventory disclaimer, and the folded "Condition, pickup & policies" fine print.

## Configuration

| key | default | effect |
| --- | --- | --- |
| `relist_grace_days` | `3` | Days an auction winner who has not started an order gets before they forfeit and the hourly tick relists the auction. |
| `fineprint_enabled` | `true` | When `false`, the `<details>` fine-print fold (the wrapper hooks at priorities 24 and 28 on `woocommerce_single_product_summary`) is not rendered — the lines inside it print unfolded. |
| `retail_source_template` | Google Shopping search URL | Where the "source ↗" link on the "% below retail" line points; `{query}` is replaced with the URL-encoded product title. Overridable per product via `_et_retail_source` meta. |

Values are read through `empire_auction_config( $key )`. Defaults are merged with the `factorize-auctions_options` option (an array stored in `wp_options`; the legacy `empire-auction-engine_options` option is still read as a fallback), and the result passes through the `factorize-auctions_config` filter, so either can override a key site-wide.

The auction cycle length itself still comes from the pre-existing `et_auction_days` option (default 7), unchanged from the theme.

## Works with

- **Ultimate Auction for WooCommerce** (required for anything to render): this plugin reads/writes its `woo_ua_*` post meta and its `woo_ua_auction_log` table, and piggybacks its bid handler (`uwa-place-bid` on `init`) and its `is_woo_ua_closed()` classification.
- **WooCommerce** (required): products, orders, notices, admin product fields.
- **factorize-catalog** (sibling plugin): `empire_tools_refresh_featured()` is called from the hourly tick via the `empire_tools_refresh_featured_safe()` wrapper, which is `function_exists()`-guarded — without that plugin the tick simply skips the Featured refresh.
- **Early-access gate**: the quick-bid button checks `empire_tools_auction_started_for_user()` only if it exists; without it the button just renders whenever the auction is open.
- The theme keeps all CSS for the classes this plugin outputs (`et-quick-bid`, `et-buy-now`, `et-card-extras`, `et-fineprint`, …).

Everything degrades gracefully: with a sibling function missing the related feature is skipped, nothing fatals.

## Hooks it registers

- `init` (priority 5): billing-details bid gate — blocks `uwa-place-bid` from unverified accounts.
- `init`: schedules the hourly `et_auction_tick` cron event.
- `et_auction_tick`: (20) refresh Featured via the guarded wrapper; (default) roll ended auctions — finalize sold-out, relist failed or ghost-winner cycles.
- `woocommerce_single_product_summary`: 7 hide reserve-not-met noise pre-bid, 9 verify notice, 12 retail line, 24 fine-print open, 27 returns line, 28 inventory note + fine-print close, 29 quick-bid button, 30 "or skip the bidding" divider, 31 grayed-out Buy Now.
- `woocommerce_after_shop_loop_item_title` (12): card extras.
- `woocommerce_order_status_processing` / `woocommerce_order_status_completed` / `woocommerce_payment_complete` (20): consume one unit per paid auction order, then relist or finalize.
- `woocommerce_product_options_general_product_data` / `woocommerce_process_product_meta`: per-product Returns select (`_et_returns_mode`).
- `wp_enqueue_scripts`: enqueues `assets/js/quick-bid.js` (handle `empire-tools-quick-bid`) on single product pages.
- `admin_init`: registers the plugin's card (Selling category) with the shared Factorize admin hub.

## Price-claim verification

Every "% below retail" line on product pages carries a **source ↗** link so shoppers can check the number: it opens the `retail_source_template` config URL (default: a Google Shopping search for the exact product title, where the same or near price listings appear). Paste a specific listing URL into a product's `_et_retail_source` meta to link straight to it.

## Publishing

`readme.txt` (the WordPress.org listing, with the full feature and roadmap breakdown) and `QUICKSTART.md` (the 5-minute setup guide) live alongside this file for the WordPress.org release.
