Harry's WheelPros API Sync

API-first rebuild of the Harry's Tire Service WheelPros wheel catalog, replacing the legacy CSV/SFTP importer with direct WheelPros API integration. Built with GitHub Spec Kit (spec-driven development).

Status

Phases 1–2.5 implemented. Catalog is parent design + variations (not a raw SKU dump). Current plugin version: 0.5.3. Requires PHP 8.2 or newer.

[x] Constitution            .specify/memory/constitution.md (v1.1.0)
[x] Feature 001 (Phase 1)   API client + diagnostics — IMPLEMENTED & verified on staging
[x] Feature 002 (Phase 2)   Catalog display (read-only) — IMPLEMENTED
[x] Feature 003 (Phase 2.5) Brand curation + reliable grouping + variations modal — IMPLEMENTED
[x] Parent UX polish        Clean design titles, multi-option card copy, Rebuild catalog now

Parent design model (current)

- Grid cards = parent designs (clean title, options count)
- Multi-option cards show "Multiple sizes & finishes" (not one SKU's specs)
- "View All Options" modal = variation table + Size/Finish/Bolt filters
- Brand allowlist scopes Harry's ~25 brands (empty = all brands)
- Settings → Rebuild catalog now applies grouping/title changes immediately

Known issues feature 003 addressed

- Catalog spans all ~10k WheelPros SKUs; Harry's carries ~25 brands → admin brand allowlist
- Same design at different sizes splits into many "1 Options" cards → reliable style key
- Different designs could merge → brandCode|designName|skuModelPrefix key prevents false merge
- "View All Options" modal opens EMPTY → populated variations table + Size/Finish/Bolt selectors
- Cards looked like SKUs → clean design titles + parent-card presentation

Phase 1 result (live on staging)

Diagnostics / Connections page working. Confirmed statuses:
  Auth       Connected (200)
  Products   Connected (200)
  Pricing    Connected (200)   (Company = sales-org code + Sample SKU set)
  Warehouse  Connected (200)
  Vehicle    Forbidden (403)   (entitlement — support request drafted)
  Inventory  Forbidden (403)   (entitlement)

Related locations

Legacy plugin (reference only, DO NOT EDIT):
/Users/macphersondesigns/Wordpress Development/Plugins/harrys-wheelpros-importer

API lab (Postman collection + entitlement notes):
/Users/macphersondesigns/Wordpress Development/Plugins/harrys-wheelpros-api-lab

Staging site (LocalWP):
https://harrystireservice.local/
/Users/macphersondesigns/Local Sites/harry-tire-service/app/public
(plugin symlinked into wp-content/plugins/harrys-wheelpros-api-sync)

High-level master plan (cross-phase):
./PLAN.md

Spec Kit workflow

/speckit.constitution   done — governing principles
/speckit.specify        done — feature 001 baseline spec
/speckit.clarify        optional — de-risk ambiguities before planning
/speckit.plan           done — feature 001 implementation plan
/speckit.checklist      optional — validate spec quality
/speckit.tasks          done — feature 003
/speckit.analyze        optional — cross-artifact consistency before building
/speckit.implement      done — features 001–003

Phase roadmap (see PLAN.md for detail)

Phase 1  API client core + Diagnostics/Connections page   <- done
Phase 2  Product read + display + cache-safe "View All Options" + image validation  <- done
Phase 2.5 Brand curation + parent grouping + variations modal  <- done
Phase 3  Sync into WordPress (single normalizer + repository + source tracking)
Phase 4  Parity vs legacy CSV catalog, then cutover
Phase 5  Vehicle + Inventory modules once WheelPros grants entitlement

Staging checklist (after deploy)

1. wp-admin → WheelPros → Settings → select Harry's brands → Save
2. Click "Rebuild catalog now" (wait for success notice with card count)
3. Front-end [wheelpros_library]: designs with clean titles, multi Options badges
4. Open "View All Options" → table + Size/Finish/Bolt filters work
5. No prices anywhere (Call for Pricing only)

Build and test

Why this approach: Composer dependencies stay reproducible in source control, while the installable ZIP still contains vendor/ so WordPress never needs to run Composer on the live server.

composer install
composer test
./scripts/build-release.sh

The release archive is written to:

dist/harrys-wheelpros-api-sync-0.5.3.zip

Automatic updates

Production updates use the same proven Plugin Update Checker family as the legacy WheelPros importer. A vX.Y.Z Git tag runs the release workflow, which tests the plugin and attaches the installable ZIP plus version.json to a public GitHub Release. WordPress then exposes the update through its normal Plugins and Dashboard → Updates screens.

The one-time repository setup and exact publishing checklist live in docs/auto-updates.md.

First production boot

1. Confirm the server uses PHP 8.2+.
2. Upload the generated ZIP; do not upload an arbitrary source-only folder.
3. Activate the plugin. Activation queues the first background catalog warm-up.
4. Configure WheelPros credentials and Harry's brand allowlist.
5. Click “Rebuild catalog now” once and keep the existing catalog visible until it completes.
6. Open a multi-option design and confirm one variations REST request returns the full option count.
7. Confirm WP-Cron is running; a host-level cron calling wp-cron.php is recommended for predictable refreshes.

The public catalog follows a stale-while-revalidate model: visitors receive the last complete snapshot immediately, while stale or missing data is rebuilt by cron. Failed and overlapping rebuilds do not replace that complete snapshot.

Confirmed API access (from the lab)

Working:   Auth, Products, Pricing, Warehouse
Forbidden: Vehicle, Inventory (account entitlement; support request drafted)