Collector Scanner

eBay marketplace search built for trading card collectors. Filter by autograph, print run, and price simultaneously. Pulls live data from eBay's Browse API.

---

Before you start

You need three things installed. If you already have them, skip ahead.

Tool	Why	Check it's installed	If missing
Node.js 18+	Runs the app	node -v	Download from nodejs.org — pick the LTS version
Git	Pushes code to GitHub	git --version	Download from git-scm.com
A code editor	Opens .env.local to paste keys	—	VS Code is the standard

You also need:

• An eBay developer account with Production keys (App ID + Cert ID) — get them at developer.ebay.com/my/keys
• A GitHub account (github.com/signup)
• A Vercel account (vercel.com/signup) — sign in with GitHub for the smoothest setup

---

Part 1 — Run it on your computer (5 minutes)

This step proves everything works before you put it on the public internet.

Step 1.1 — Unzip and open the folder

Unzip collector-scanner.zip. You'll get a folder called collector-scanner. Open a terminal and cd into it:

cd path/to/collector-scanner

Don't know how to open a terminal?

• Mac: Press ⌘ + Space, type "Terminal", hit Enter
• Windows: Press Win + R, type powershell, hit Enter

Step 1.2 — Install dependencies

npm install

This downloads everything the app needs. Takes 30–60 seconds. Ignore any npm warn messages — they're harmless.

Step 1.3 — Add your eBay keys

Copy the example env file into a real one:

Mac/Linux:

cp .env.local.example .env.local

Windows (PowerShell):

Copy-Item .env.local.example .env.local

Now open .env.local in your code editor and replace the placeholder text with your real keys:

EBAY_APP_ID=ActualAppIdFromEbay-PRD-1234567890-abcdef
EBAY_CERT_ID=PRD-abcdef1234567890-abcd-efgh-ijkl

⚠️ Critical: Use your Production keys, not Sandbox. The toggle is at the top of developer.ebay.com/my/keys. Sandbox keys return empty data — the app will look broken even though it isn't.

Step 1.4 — Start the app

npm run dev

You'll see something like:

▲ Next.js 14.2.5
- Local:        http://localhost:3000
✓ Ready in 2.1s

Open http://localhost:3000 in your browser.

Step 1.5 — Test it

Type Mahomes auto in the search box and hit Enter. You should see real eBay listings with prices, images, and "View on eBay" links.

If it works, you're done with Part 1. Stop the server with Ctrl + C in the terminal and continue to Part 2.

If it doesn't work, jump to Troubleshooting at the bottom.

---

Part 2 — Deploy it to the internet (10 minutes)

Step 2.1 — Put the code on GitHub

In your terminal, still inside the collector-scanner folder:

git init
git add .
git commit -m "Initial commit"

Now create a new repo on GitHub:

1. Go to github.com/new
2. Name it collector-scanner (or anything you want)
3. Leave it Private if you don't want others reading your code
4. Don't check "Add a README" — your folder already has one
5. Click Create repository

GitHub will show you a few commands. Copy the ones under "...or push an existing repository from the command line" and run them in your terminal. They'll look like:

git remote add origin https://github.com/YOUR_USERNAME/collector-scanner.git
git branch -M main
git push -u origin main

Step 2.2 — Deploy on Vercel

1. Go to vercel.com/new

2. Find your collector-scanner repo in the list and click Import

3. On the configuration screen, expand Environment Variables and add all four:

   Name	Value
   EBAY_APP_ID	(paste your App ID)
   EBAY_CERT_ID	(paste your Cert ID)
   RESEND_API_KEY	(paste your Resend API key — see below)
   RESEND_AUDIENCE_ID	(paste your Resend Audience ID — see below)

4. Click Deploy

Wait ~60 seconds. Vercel will give you a live URL like collector-scanner-abc123.vercel.app. Open it and run the same test search.

You're live. 🚀

Don't have Resend keys yet? That's fine — leave those two env vars blank and the site still works. The Alerts waitlist form will return a friendly error in production until you add them. To set them up: create a free account at resend.com, create an Audience (Audiences → Create Audience → name it "Fields & Floors waitlist"), then grab the API key from API Keys and the Audience ID from the audience's settings page.

---

What's in the project

collector-scanner/
├── app/
│   ├── api/
│   │   ├── search/route.js     ← eBay OAuth + Browse API call (the backend)
│   │   └── waitlist/route.js   ← Resend Audiences signup for /alerts
│   ├── components/             ← Shared Header, Footer, Seal, PageShell
│   ├── how-it-works/           ← Editorial subpages
│   ├── filters/
│   ├── alerts/                 ← Waitlist form + page
│   ├── reading-list/
│   ├── glossary/
│   ├── contact/
│   ├── page.js                 ← The main search UI
│   ├── layout.js               ← Wraps every route with Header + Footer
│   └── globals.css             ← Colors, fonts, texture, prose styling
├── package.json                ← Lists dependencies
├── next.config.js              ← Allows eBay image domains
├── tailwind.config.js          ← Tailwind setup
├── postcss.config.js           ← CSS processor
├── .env.local.example          ← Template for your keys
├── .gitignore                  ← What Git ignores
└── README.md                   ← This file

One Next.js app, one deploy. No separate backend server.

---

How it actually works

When someone searches:

This is the beginning of the README. Read the rest at the original. Read the full README ↗