Below is a revised README you can paste as README.md:

🚀 Salesforce AppExchange Discovery Engine

Discover AppExchange apps and extract public reviews — for research, competitive intelligence, and solution selection.

The Salesforce AppExchange Discovery Engine is an Apify Actor that helps you find applications on Salesforce AppExchange by category, extract key metadata, and optionally collect public user reviews — exporting everything into clean CSV/XLSX datasets.

This Actor is intended for businessmen, developers, consultants, analysts, and teams who want to find the right applications for business purposes, especially in:

• Finance
• Human Resources
• Enterprise Resource Planning (ERP)
• Sales
• Customer Service
• IT & Admin
• Marketing
• Integration
• Salesforce Labs
• Analytics

It can also support your Agentic Enterprise journey:

Extend your Agentic Enterprise with AgentExchange
Explore the AgentExchange collection to get started faster with pre-built skills from Agentforce partners. Find solutions designed to maximize efficiency and scale AI.

---

✅ What this Actor does

You choose:

1. Sphere (where to explore on AppExchange)
2. Primary categories (e.g., finance, analytics, integration)
3. How many apps to process
4. How many reviews per app to collect (optional)

Then the Actor:

• Opens the corresponding listing pages
• Collects app URLs (deduplicated)
• Opens each app detail page to extract metadata
• Optionally extracts reviews
• Exports results to CSV / XLSX / JSON

---

🔍 Key concepts (how discovery works)

Step 1 — Choose Sphere

A “sphere” is a top-level navigation area of AppExchange.

Example:

• business_needs (implemented with URL templates)

Other spheres can be added later (products, industries, agentforce, etc.).

Step 2 — Choose Primary Categories

Within a sphere you choose categories such as:

• finance, analytics, integration, marketing, etc.

Step 3 — Apps discovery (automatic)

For each selected category, the Actor:

• loads the listing page
• clicks “Show more” / paginates
• scans listing anchors for app detail links
• builds a list of unique app_url

Step 4 — App detail extraction (automatic)

For each app URL, the Actor extracts:

• app name + vendor
• short description
• rating and reviews count
• pricing text (when visible)
• supported clouds
• the listing_id (critical for reviews)

Step 5 — Reviews extraction (optional)

If mode includes reviews, the Actor collects up to maxReviewsPerApp per app.

---

Inputs

Required

• mode: apps | reviews | apps+reviews
• categoryPreset: list of categories (within the chosen sphere)

Optional

• sphere (default: business_needs)
• maxPages (default: 10) — how many “load more / scan steps” to attempt per category
• startIndex / endIndex — slice which apps to process (useful for testing)
• maxReviewsPerApp — limit reviews per app (0 = unlimited)
• headless — run browser headless
• proxySettings — proxies for large runs (optional)

---

🧪 Input example (recommended)

{
  "mode": "apps+reviews",
  "sphere": "business_needs",
  "categoryPreset": ["finance", "analytics", "integration"],
  "maxPages": 3,
  "maxReviewsPerApp": 20,
  "startIndex": 1,
  "endIndex": 50,
  "headless": true,
  "proxySettings": {}
}
 
 What maxReviewsPerApp means
maxReviewsPerApp = 20 → extract up to 20 reviews per app
maxReviewsPerApp = 0 → extract all available reviews (can be large)

📦 Outputs
Apps output
Saved as:
•	APPS.csv
•	APPS.xlsx
Each row includes:
•   listing_id (required for reviews)
•	sphere
•	primary_category_name
•	app_name, vendor, short_description
•	rating, reviews_count
•	price_text, clouds
•	app_url, last_seen_at
•	plus technical compatibility fields: listing_id, name, url
Reviews output
Saved as:
•	REVIEWS.csv
•	REVIEWS.xlsx
Each row includes:
•	listing_id
•	review date
•	rating
•	review text
•	reviewer (public display name, if available)
 Reviews dataset (REVIEWS)

Saved as:

REVIEWS.csv

REVIEWS.xlsx
(plus dataset items in Apify storage)

Reviews include fields like:

•listing_id
•rating
•review text
•author (public)
•date
•etc. (depends on reviews extractor)

Where to find results locally

If you run locally with APIFY_LOCAL_STORAGE_DIR set, you will see:

APPS.csv, APPS.xlsx in project root
REVIEWS.csv, REVIEWS.xlsx in project root (when reviews run succeeds)
Debug KV records under:

apify_storage/key_value_stores/default/DEBUG_APPS_RUN.json
🧯 Troubleshooting
“No reviews files created”
This usually means your apps file does not contain listing_id.
Fix:
•	ensure APPS.csv includes listing_id
•	re-run apps+reviews
“Row X has no listing_id; skipping”
Same issue: listing_id missing or empty.
 
🔐 Compliance
•	Collects publicly available information only
•	No login required
•	No gated/private data accessed
•	Users are responsible for compliance with Salesforce terms and local regulations
 
💰 Pricing / Monetization (recommended)
Pay-per-event model:
•	1 event = 1 dataset item written
(app rows + review rows)
Use endIndex and maxReviewsPerApp to control cost.

---

If you want, paste your current `reviews/reviews_runner.py` (the part where it reads APPS.csv), and I’ll also make it **more robust** by adding a fallback:

- if `listing_id` missing → parse it from `app_url` automatically

That makes the pipeline much harder to break.
::contentReference[oaicite:0]{index=0}

Monetization recommendation (based on your inputs)
Because your main “cost drivers” are:
•	number of apps processed (endIndex, maxPages, categories count)
•	number of reviews extracted (maxReviewsPerApp)
Best model: Pay Per Result (Pay-Per-Event)
Define 1 event = 1 output item written:
•	each app row written → 1 event
•	each review row written → 1 event
This is transparent and scales fairly.
Practical defaults for users (recommended)
•	maxReviewsPerApp: 20 default (safe)
•	endIndex: 50 default (demo-size)
•	require users to increase for bigger jobs
Why this is best for Apify Store
•	users can predict cost:
events ≈ apps + (apps × maxReviewsPerApp) (upper bound)
•	you avoid surprise bills when reviews are huge
•	easy to explain on Store page