# BuyLowa API-ready marketplace prototype

BuyLowa is a product search and price comparison website. This version is built so the front end already behaves like it is talking to an API, even before live marketplace APIs are connected.

## What this version is

This is a static front end with a mock API fallback and a Cloudflare Worker scaffold.

- The page is functional with local demo data.
- The front end uses `js/api/client.js` instead of reading products directly inside the UI.
- In `auto` mode, the site tries `/api/search` first, then falls back to local demo data if the Worker is not running.
- The Worker has provider adapter files waiting for eBay, Amazon, Kogan, and generic affiliate feeds.
- Product results use one normalised BuyLowa product shape.

## Run locally

Use a local server such as VS Code Live Server.

Do not open `index.html` directly from the file system, because browser security rules can block local JSON/module loading.

## Important files

```text
index.html
style.css
css/
js/
data/
worker/
docs/
pages/
```

## Frontend data flow

```text
User searches
↓
js/main.js updates state
↓
js/api/client.js calls /api/search when available
↓
If the Worker is unavailable, mockApi searches data/demo-products.json
↓
Results render through the same UI components
```

## Switch to live Worker mode

Open:

```text
data/site-config.json
```

Change:

```json
"apiMode": "auto"
```

To:

```json
"apiMode": "worker"
```

Only do this after the Worker is deployed and `/api/search` is reachable.

## Where API keys go

Never put API keys in frontend JavaScript.

Use Cloudflare Worker secrets:

```bash
wrangler secret put EBAY_CLIENT_ID
wrangler secret put EBAY_CLIENT_SECRET
wrangler secret put AMAZON_ACCESS_KEY
wrangler secret put AMAZON_SECRET_KEY
wrangler secret put KOGAN_FEED_TOKEN
wrangler secret put AFFILIATE_NETWORK_TOKEN
```

## Add a provider

1. Add a new adapter file inside `worker/adapters`.
2. Return products using `normalizeProduct()`.
3. Add the adapter to `worker/adapters/providerRegistry.js`.
4. Add the provider metadata to `data/providers.json` for the frontend.
5. Test `/api/search`.

## Demo vs live

See:

```text
docs/fake-vs-real.md
```

## Validation

A simple project checker is included:

```bash
npm run check
```

It checks required files, JSON validity, and JavaScript syntax.