ebay-search-listing

# eBay — Search & Category Listing Extraction

> Input: any eBay search or category page URL → Output: paginated array of item cards (itemNumber, url, title, price, seller, image, etc.) plus pagination state (currentPage, nextPageUrl, hasNextPage, totalResultsApprox).

## Language

All process output to user (progress updates, process notifications) follows the user's language.

## Objective

Given any eBay search results URL (SRP) or category URL, extract the visible product cards on the current page with their key surface fields, and expose pagination state so a caller can loop pages until an item cap or the last page is reached.

## Prerequisites

- Target page is already open in the browser: `https://www.ebay.{tld}/sch/i.html?_nkw={keyword}` (search) or `https://www.ebay.{tld}/b/{category-slug}/{category-id}/bn_...` (category), where `{tld}` is any eBay regional TLD (`com`, `co.uk`, `de`, `fr`, `it`, `es`, `com.au`, `ca`, `co.jp`, `com.hk`, `in`, `ph`, `pl`, `nl`, `ie`, `at`, `be`).
- No login is required for public listings. Extraction runs against whatever the anonymous browser session sees.

## Pre-execution Checks

### 1. Tool Readiness

If browser-act has been confirmed available in the current session → skip this step.

Invoke `browser-act` via Skill tool to load usage. If installation or configuration issues arise, follow its guidance to resolve then retry.

## Capability Components

> This Skill's operational boundary = what the user can manually do in their browser. It only reads data already displayed to the user on the page, never bypassing authentication or access controls. Its role is equivalent to copy-pasting on the user's behalf — the data is already on screen, automation merely saves time. JS code is encapsulated in Python files under the `scripts/` directory, invoked via `eval "$(python scripts/xxx.py {params})"`. `$(...)` is bash syntax; it is recommended to use the bash tool for execution.

Below are all atomic capabilities discovered and verified during the exploration phase. Simply invoke them as needed — no need to read `scripts/*.py` source code or re-verify. Only inspect scripts when execution fails for troubleshooting.

### DOM: extract item cards from the current search or category page

Precondition: `navigate {search or category URL}` → `wait stable` first.

Extract: `eval "$(python scripts/extract-listing.py --max-items 0)"`

Parameters:
- `--max-items`: Cap on cards returned from the current page. `0` (default) returns every card on the page. Use a positive integer when the caller only wants the top-N of the current page (does not affect pagination state).

Output example:
```json
{
  "currentUrl": "https://www.ebay.com/sch/i.html?_nkw=headphones&LH_BIN=1",  // page URL as observed
  "hostname": "www.ebay.com",                       // regional domain of the current page
  "currentPage": 1,                                 // 1 when the URL has no _pgn param
  "nextPageUrl": "https://www.ebay.com/sch/i.html?_nkw=headphones&LH_BIN=1&_pgn=2",  // null when on last page
  "hasNextPage": true,                              // false = last page reached
  "totalResultsApprox": 250000,                     // parsed from the results-count heading; null if not shown
  "totalResultsRaw": "250,000+ results for headphones",  // original heading text
  "itemsOnPage": 60,                                // eBay default is 60 per page; can be overridden by _ipg URL param
  "returnedCount": 3,                               // number of items in the "items" array below (respects --max-items)
  "items": [
    {
      "itemNumber": "195486024424",                 // eBay listing id (also from data-listingid on the card)
      "url": "https://www.ebay.com/itm/195486024424",  // canonical item URL, query params stripped
      "title": "Plugfones Guardian OSHA Certified earplug with audio Work Headphones earbuds",
      "subtitle": "Brand New",                      // condition / seller-type badge; null when absent
      "caption": null,                              // e.g. "New Listing", "Sold Jul 7, 2026"; null when absent
      "price": 24.99,                               // parsed numeric price
      "priceWithCurrency": "$24.99",                // original price string
      "currency": "USD",                            // ISO code detected from price prefix
      "wasPrice": null,                             // original / strikethrough price if shown
      "wasPriceWithCurrency": null,
      "bids": null,                                 // auction bid count; null for BIN listings
      "shipping": "+$12.99 delivery",               // shipping-row text as displayed; null when absent
      "seller": "plugfones",                        // seller username
      "sellerRawText": "plugfones 99.7% positive (15.9K)",  // original seller badge text
      "sellerFeedbackCount": 159000,                // parsed from (15.9K); handles K suffix
      "sellerPositiveRating": 99.7,                 // percentage as float
      "reviewsCount": null,                         // product-review count when displayed on the card
      "starRating": null,                           // 0-5 star rating when displayed
      "image": "https://i.ebayimg.com/images/g/PbYAAOSwuHdjcqCX/s-l1600.webp"  // upgraded to s-l1600 for the largest available crop
    }
  ]
}
```

Error handling:
- When `.srp-results > li.s-card` matches zero elements, the script returns `{"error": true, "message": "no item cards found ..."}`. Root causes: the page navigated to an item detail (URL contains `/itm/`), an anti-bot interstitial is shown, or eBay changed the class prefix. Take a `screenshot` first, verify the URL is still an SRP or category page, then retry.
- When the browser is fingerprinted and eBay serves a captcha page, follow the standard captcha escalation (`solve-captcha`, headed handoff, `remote-assist`).

## Pagination

**URL Pagination**: URL pattern `?_pgn={page}` (append `&_pgn=N` to any search or category