# Auction-Pipeline Outbound — Integration Spec

> Researched 2026-06-17. Fills the gap flagged in the pipeline pressure-test:
> the current plan exports a *generic* auction CSV (`buildAuctionExportCsv`),
> but estate/auction sellers actually live in specific marketplace feeds and
> auction-management software. This spec captures the real import formats and a
> TroveSnap adapter design.
>
> **All targets are Auth + connector gated** (phase 2). File-based exports can
> ship earlier than the API/two-way integrations. Specs below are reported from
> vendor docs and should be re-verified before building any adapter — the
> LiveAuctioneers guide sampled here is dated (V3.3, 2018).

## Why generic CSV isn't enough

There is **no universal interchange format** — each marketplace has its own
template, field constraints, and image rules. That fragmentation is exactly the
pain. The TroveSnap move: **normalize once into the canonical record, emit a
per-target package (template + lot-numbered images), as a reviewed draft, never
auto-posted** — the candidate-style outbound mirror of the ingestion contract.

## Target platforms & how each ingests

| Platform | Ingest method | Notes |
| --- | --- | --- |
| **LiveAuctioneers** | Spreadsheet (XLSX → save as CSV / tab-delimited) + images via FTP / hosted URL | Strict field rules (below). Images named by lot number by default. Auction software (Auction Flex, RFC, BidMaster) can export CSV for direct upload. |
| **Proxibid** | Bulk Loader: Excel/CSV with column mapping | Multi-image naming `1-1`, `1-2` (lot-image). Wavebid has a direct two-way integration. |
| **Invaluable (+ AuctionZip + private-label)** | **Catalog Upload API for auction-software partners** | Not a raw consignor CSV — reached via partner API or via Auction Flex / Wavebid. |
| **Auction Flex → HiBid** | Spreadsheet import into Auction Flex; native one-click upload to HiBid | Lot numbers present → into an auction; absent → into inventory. Auction Flex is the dominant live-auction mgmt app. |
| **Wavebid** | "Universal Export"; two-way API integrations | Direct export + **sale-results pull-back** for Proxibid and Invaluable/AuctionZip; LiveAuctioneers manual export + manual results import. |

## LiveAuctioneers field spec (the reference template)

**Mandatory columns:** `LotNum` · `Title` · `Description` · `LowEst` · `HighEst`
· `StartPrice`

- `LotNum` — ≤10 chars; optional trailing alpha to disambiguate (`27`, `27A`), no space.
- `Title` — ≤49 chars including spaces; put searchable words first.
- `Description` — no length limit; simple HTML allowed; line breaks as `<br>`;
  **no website links**; include dimensions, age, materials, maker, damage.
- `LowEst`, `HighEst`, `StartPrice` — **no currency symbols**;
  `LowEst ≤ HighEst`, `StartPrice ≤ LowEst`; empty StartPrice defaults to 50% of LowEst.

**Optional columns:** `Condition` · `Consignor` (internal, not displayed) ·
`ImageFile.1`–`ImageFile.20` · `Buy Now Price` · `Exclude From Buy Now` (0/1) ·
`Reserve Price` · `Height` / `Width` / `Depth` / `Dimension Unit` (in/ft/cm) ·
`Weight` / `Weight Unit` (oz/lb/g/kg) · `Quantity`.

**Images** — named by lot number by default (`24.jpg`, `24-2.jpg`, …) OR listed
explicitly in `ImageFile.N` (full filename incl. `.jpg`, case-sensitive), or a
hosted URL the processor fetches. Save the sheet as CSV/tab to preserve special
characters.

## TroveSnap field mapping (canonical → LiveAuctioneers)

| TroveSnap canonical | → LiveAuctioneers | Transform / validation |
| --- | --- | --- |
| item title | `Title` | truncate/warn at 49 chars |
| AI/edited listing copy | `Description` | HTML-safe, strip links, `<br>` newlines |
| internal low/high guidance | `LowEst` / `HighEst` | strip `$`; enforce low ≤ high |
| suggested starting bid (~40% of high) | `StartPrice` | reuse `suggestStartingBid`; ≤ low |
| reserve (60% when ≥ $500) | `Reserve Price` | reuse existing disposition logic |
| condition | `Condition` | pass-through |
| seller / consignor | `Consignor` | internal only |
| item photos | lot-numbered files / `ImageFile.N` | emit image bundle named by lot |
| dimensions / weight (if known) | `Height/Width/Depth` + units | unit normalize |
| lot quantity | `Quantity` | whole-lot price only |

Most of this already exists in `troveDisposition.ts` (`buildAuctionExportCsv`,
`suggestStartingBid`) — the work is generalizing it from one CSV to a
per-target **export profile**.

## Recommended adapter design

1. **Export profiles** — one per target (`liveauctioneers`, `proxibid`,
   `auctionflex`, `hibid`, `invaluable`, `wavebid`, `generic`). A profile =
   column map + field validators + image-naming rule.
2. **Image-bundle emitter** — the structural piece the current CSV export
   lacks: produce a folder/zip of images named by lot number (and the
   `1-2`/`24-2` sequence convention), or fill `ImageFile.N`.
3. **Validation surfaced in review** — warn before download on title > 49,
   missing/!ordered estimates, currency symbols, links in description, missing
   lot numbers. Same review-gate spirit as the ingestion contract.
4. **Reviewed draft only** — produces a downloadable package; never auto-posts.
5. **Phasing within phase 2:**
   - **2a — file exports (earlier):** LiveAuctioneers / Proxibid / Auction Flex
     spreadsheet + lot-numbered image bundle. The *file* needs no third-party
     Auth.
   - **2b — API + two-way (needs Auth/connectors):** Invaluable Catalog Upload
     API; Wavebid/Proxibid/Invaluable **sale-results pull-back** →
     `inventory_status_events` → recovered-revenue analytics. LiveAuctioneers
     results remain manual import.

## Settlement / results back (closing the loop)

The inbound half: pull post-sale results (sold / passed / hammer price) from
Proxibid, Invaluable/AuctionZip (direct), or manual for LiveAuctioneers, into
the existing reconciliation path (`inventory_status_events`, sold price) so
recovered-revenue and disposition-outcome analytics reflect actual auction
results. Consignor-settlement reports are a later, finance-side extension.

## Sources

- LiveAuctioneers — Guide to your Catalog Text Format (V3.3); seller knowledge base.
- Proxibid — Welcome Packet (Bulk Loader); Wavebid Proxibid integration docs.
- Invaluable — Catalog Upload API info (partner API for AuctionZip + private-label).
- Auction Flex — importing lots; upload-to-HiBid help.
- Wavebid — integration guide (LiveAuctioneers / Proxibid / Invaluable export + results pull).
- Gavelist — native export targets (confirms the canonical target list).

*Reported from vendor docs; re-verify current templates, field limits, and image
rules with each platform before building an adapter.*