Kuantum Facebook Marketplace Basketball-Card Monitor

This project searches Facebook Marketplace through an authorized existing Chrome profile and enriches captured listing URLs with the Apify Actor bczOsNg3SNbHUqjHm. It does not enter credentials, bypass login or security controls, or claim that Facebook exposes every possible listing.

What it adds

• Canonical listing IDs and URL deduplication before Actor charging.
• Batch discovery across multiple search phrases, ZIP code, and radius.
• Public search-card title, price, location, and image capture.
• Distance from the search ZIP. Listing coordinates are used when Facebook publishes them; otherwise the workbook clearly labels a city-center estimate.
• Conservative listing status: active_visible, sold, pending, removed_or_unavailable, missing_from_search, or possibly_sold_or_removed.
• New-listing, price-drop, status-change, duplicate, and possible-relisting history.
• Basketball-card relevance classification with Needs Review and Excluded queues.
• Structured player, year, brand, set, card number, grading company, grade, quantity, vintage indicator, and comparable-sales readiness fields.
• Optional OCR of the first public listing image for unclear records.
• Excel sheets for basketball-card sales, review items, exclusions, new listings, price reductions, status changes, duplicates, inactive records, all records, and a run summary.
• Session-health circuit breaker, optional HTTPS webhook alerts, and native macOS notifications from the daily local monitor.

Daily Orlando search

The configuration in config/basketball-cards-32801.json searches these phrases around ZIP 32801 within 100 miles:

• basketball cards
• NBA cards
• vintage basketball cards
• basketball card collection
• graded basketball cards
• Michael Jordan cards
• Kobe Bryant cards
• LeBron James cards

The macOS LaunchAgent runs at 8:00 AM local time and calls:

$node scripts/run-daily-monitor.mjs

The script reopens only the existing authorized profile at /Users/ricardoprieto/facebook-marketplace-chrome-session when necessary. It captures current search results, updates persistent monitoring state in protected Apify store MPmiMb9ZPSKIQdsCt, writes a local Excel workbook, and optionally runs the Actor for full-page enrichment. Actor runs have a per-run ceiling configured by maxTotalChargeUsdPerRun.

Latest local file:

outputs/facebook-marketplace-basketball-cards-32801-100mi-latest.xlsx

Latest protected-store records:

• MONITOR_OUTPUT_XLSX
• MONITOR_SUMMARY
• MONITOR_STATE_BASKETBALL_CARDS_32801_100MI
• MONITOR_EVENTS_BASKETBALL_CARDS_32801_100MI

Facebook connection window

Start the local connection screen with:

$npm run facebook:connect

It opens http://127.0.0.1:4318/ in the monitor's existing Chrome profile. Use Open Facebook login to complete Facebook login and two-factor authentication manually. Then use Verify & save session to check Marketplace visibility and refresh PLAYWRIGHT_STORAGE_STATE in protected Apify store MPmiMb9ZPSKIQdsCt.

The connector binds only to localhost, rejects cross-origin state changes, and never exposes the Apify token to the browser. It has no credential fields and never reads or stores a Facebook password. Before upload, browser storage is reduced to Facebook domains only. The control screen reports Connected, Login Required, Security Check, or Connection Check Failed without returning cookie contents. Login instructions stay hidden while connected and automatically return when the connection needs attention.

The same screen previews the current Basketball Card Sales workbook sheet. It renders four listings initially and loads the next four when the user scrolls to the bottom. Preview pagination reads the existing Excel file and does not make additional Facebook or Apify requests.

Manual capture and processing

With the existing Chrome profile running on CDP port 9222:

SEARCH_URL='https://www.facebook.com/marketplace/orlando/search/?query=basketball%20cards&zipCode=32801&radius=100' node scripts/capture-marketplace-search.mjs
node scripts/process-captured-monitor.mjs

SEARCH_URLS_JSON accepts up to 20 Marketplace search URLs for batch capture. The helper closes only its own page and never closes the user-owned browser.

Actor input

Use captured results with conservative request pressure:

{
  "capturedListingStoreId": "MPmiMb9ZPSKIQdsCt",
  "maxItems": 200,
  "maxConcurrency": 1,
  "requestDelayMs": 4000,
  "radiusMiles": 100,
  "monitorMissingListings": true,
  "missingRunsBeforeInactive": 3,
  "monitoringScope": "basketball-cards-32801-100mi",
  "enableImageOcr": true,
  "maxOcrItems": 10,
  "alertOnNewListing": true,
  "alertOnPriceDrop": true,
  "alertOnSessionHealth": true,
  "useFacebookSession": true,
  "facebookSessionStoreId": "MPmiMb9ZPSKIQdsCt",
  "useApifyProxy": false
}

Every run writes OUTPUT_XLSX, OUTPUT_CSV, OUTPUT_MD, RUN_SUMMARY, and RUN_CHANGES. Search diagnostics are saved as SEARCH_###_SUMMARY, HTML, and screenshot records.

Alerts and schedules

Set alertWebhookUrl to an authorized HTTPS endpoint for new-listing, price-drop, session-health, and run-complete JSON events. The daily local monitor also uses native macOS notifications without requiring an external service.

scripts/create-schedule.mjs creates or updates an Apify cloud schedule using the current cronExpression, runInput, and email-notification format. It defaults to disabled so a separate cloud schedule cannot accidentally duplicate the active local daily workflow.

Limitations

• Facebook controls search exposure, ranking, and radius behavior. Multiple phrases and repeated captures improve recall but cannot guarantee completeness.
• City-only locations produce an estimated distance, not an exact seller address. Missing locations remain unknown rather than guessed.
• A listing absent from search is not conclusively sold. It becomes possibly_sold_or_removed only after consecutive healthy captures; an explicit public page signal is required for a high-confidence sold or removed_or_unavailable status.
• Comparable-sales pricing is not guessed. comps_readiness shows which records have enough structured attributes for a separate sold-comps source.