`scripts/clothing-apis/README.md`

59 lines
# Clothing-API catalog ingestion

Pulls real product catalogs into `items` from public + free clothing APIs.

## Sources, ranked by friction

| Tier | Source | Key needed? | Yield per brand |
|---|---|---|---|
| 🟢 None | Shopify `/products.json` | No | 250 / page × pages |
| 🟡 Free | Etsy Open API v3 | `ETSY_API_KEY` | 25 / page × pages |
| 🟡 Free | eBay Browse API | `EBAY_OAUTH_TOKEN` | 50 / page × pages |
| 🟡 Free | Amazon PAAPI 5 | via `amazon-paapi-integration` skill | 10 / page (rate-limited) |
| 🟡 Affiliate | Awin / Rakuten / CJ / Impact | network-specific | bulk feeds |

## Run

```bash
# Import every Shopify brand in brands.json (zero key)
node scripts/clothing-apis/index.js shopify

# Import one brand
node scripts/clothing-apis/index.js shopify allbirds

# Programmatic — from server admin endpoint
POST /api/admin/import-catalog  { "kind": "shopify" }
POST /api/admin/import-catalog  { "kind": "shopify", "id": "cuyana" }
```

## Adapter rules

1. **Identify the bot** in `User-Agent: WhatsMyStyleBot/0.1 (steve@designerwallcoverings.com)` so brands can rate-limit us if they need to.
2. **Be nice** — 600-1000ms between pages, cap pages per brand.
3. **Skip broken rows** — no image OR no price OR no recognized category → don't insert. Better a smaller, clean catalog.
4. **Idempotent** — `INSERT OR IGNORE` on `UNIQUE(source, external_id)` so re-runs add only new SKUs.
5. **Map to category enum** — `top` | `bottom` | `dress` | `outerwear` | `shoes` | `bag` | `accessory`. Anything that doesn't map is dropped.

## After import

Newly imported items have `embedding IS NULL`. They won't appear in duels or recs until embeddings are computed. Run:

```bash
node scripts/embed-items.js <limit>     # llava → 32-d projection
```

## Adding a new brand

1. Append to `scripts/clothing-apis/brands.json` `shopify_dtc` array:
   ```json
   { "id": "yourbrand", "name": "Your Brand", "domain": "yourbrand.com", "sustain_tier": 4, "pro_grade": 1 }
   ```
2. `node scripts/clothing-apis/index.js shopify yourbrand`
3. That's it. The adapter is generic — every Shopify-powered DTC site Just Works.

## Notes

- The `pro_grade` flag is what set-decorator filter uses (`?pro_only=1`). Multi-stock brands get `pro_grade: 1`; resale-only (Etsy / eBay) stays at `0`.
- The `sustain_tier` is informational — for now `scripts/sustainability.js` is the canonical lookup; this seed is a backstop.
- We never persist email bodies, partner cookies, or anything besides the public product fields shown above. See `/privacy-policy`.