`README.md`

67 lines
# fineartamerica-price-sync

Keeps Designer Wallcoverings Shopify prices for **Fine Art America (FAA) fulfilled
products** (framed prints, posters, canvas, metal — vendor `Steve Abrams Studios`)
safely above their live FAA fulfillment cost, so an order can never lose money the
way it did on the Washington Top Hat 20"×24" (sold $110 while costing more to
fulfill).

## Why this exists

Each Shopify variant SKU **is** a full FAA order string:

```
artworkid[65269183]-productid[printframed]-imagewidth[20]-imageheight[24]
-paperid[archivalmattepaper]-frameid[CRQ13]-mat1id[PM918]-mat1width[2]
-finishid[0.125acrylic]
```

So cost lookup is deterministic. FAA raises base/material prices over time; static
Shopify prices silently slide underwater. This syncs them and guards them.

## Pricing rule

`retail = FAA_cost / 0.65 / 0.85` (~**1.81×** cost) — the DW wallcovering formula,
Steve-selected 2026-07-16.

## Cost source

FAA only prices an exact size/frame/mat/finish combo through its live JS
configurator, so per-variant cost is fetched via a **logged-in Browserbase
session** (`bin/faa-fetch.js`) and cached in `data/cost-cache.json` keyed by the
config string. Plain HTTP only yields the product-type default price.

Credentials (`FAA_EMAIL`, `FAA_PASSWORD`, `SHOPIFY_ADMIN_TOKEN`,
`BROWSERBASE_*`) live in `~/Projects/secrets-manager/.env` — never in this repo.

## Usage

```bash
# 1. learn a listing's configurator DOM (once per FAA listing)
node bin/faa-fetch.js --url "<faa product page>" --inspect

# 2. fetch + cache real FAA costs for a Shopify product's variants
node bin/faa-fetch.js --url "<faa product page>" --from-shopify 7549840293939

# 3. dry-run the reprice (writes data/dry-run.csv, no live writes)
node sync.js --product 7549840293939

# 4. GATED live write — only after Steve approves the dry-run
APPLY_CONFIRM=YES node sync.js --product 7549840293939 --apply

# loss-guard canary (read-only; exits non-zero on any below-cost variant)
node canary.js --variant 43235375022131
node canary.js --all
```

## Hard rules

- `designer-laboratory-sandbox.myshopify.com` is the **LIVE** production store.
  `--apply` is customer-facing money and requires `APPLY_CONFIRM=YES` + Steve's
  approval of the dry-run.
- Never invent a cost. A config with no cached FAA cost is reported `COST-UNKNOWN`
  and left untouched.
- Data-integrity watch: a variant SKU's `artworkid` can differ from the current
  FAA listing id (Washington Top Hat: SKU `65269183` vs live listing `65119339`) —
  the fetch resolves against the listing you actually fulfill.