Local Listings

All steps (reference)

1. Step 1. Open Local listings

   From a project, open Business → Local listings. Orgs without the addon see the upgrade page instead of a bare 403. Click **Find listings** to open the slide-over: multi-select directories for Find selected, and Manual URL (directory + paste + Confirm URL) in the same panel. Providers that are not wired show as not configured (disabled).

   What to do: Project sidenav → Business → Local listings → Find listings

   Where: directory-listings.index

   

   Expected (pass)

   • Page title Local listings with a single Find listings action
   • Find listings slide-over shows directory checkboxes and Manual URL
   • Not-configured note when a provider lacks BrightData setup

   Negative cases (must fail safely)

   • Addon off → upgrade page (directory-listings.upgrade)
   • Cross-org project id → 403/404

2. Step 2. Discover and confirm a BBB match

   In Find listings, select BBB (and peers if you want), then Find selected. Candidates come from Business Profile, then Local SEO / Alignment NAP for blanks (cache-first, then SERP). When a website domain is known, SERP is domain-first on bbb.org; otherwise name + city + state. Confirm a suggestion, or use Manual URL in the same panel with a https://www.bbb.org/… link. After Confirm, the URL stays under Linked as Confirming… until enrichment finishes (the page updates live). Multi-location businesses always need human confirm. Find is free; Confirm uses a monthly unlock or credits.

   What to do: Find listings → select BBB → Find selected → Confirm (or Manual URL → Confirm URL)

   Where: directory-listings.index

   

   Expected (pass)

   • Suggested matches panel with confidence scores
   • Confirm keeps the selected URL visible as Confirming… while enrichment runs
   • On success a linked listing appears with provider, role, and match %
   • On Incomplete / Failed, no project link is created and the unlock is refunded; the pick can be retried

   Negative cases (must fail safely)

   • Non-BBB URL → validation error
   • Allowance spent and no credits → blocked with a top-up-style message
   • Thin BBB payload → Incomplete / Failed with refund (retry later or try another URL)
   • BBB not configured → disabled in Find slide-over / Confirm URL not-configured alert

   Tips

   • Cache hits for a complete, fresh profile link immediately without a new scrape when the org already unlocked that external id.
   • If Incomplete keeps happening on good BBB URLs, tell an admin — the scrape source may be returning less data than expected.

3. Step 3. Discover and confirm other directories

   In Find listings, select Yelp / Angi / Trustpilot / G2, or use Manual URL in the same panel. Discovery uses the same signal resolver as BBB (Business Profile → Local SEO → Alignment NAP) and domain-first SERP when a website is known. Confirm keeps the selected listing visible until enrichment finishes — it does not disappear from the page. Yelp overview unlock can auto-enqueue reviews when the Yelp reviews dataset is set. Closed Yelp businesses still unlock and show a Closed on Yelp badge. Angi, Trustpilot, and G2 never auto-confirm at 100%.

   What to do: Find listings → select providers → Confirm, or Manual URL → Confirm URL

   Where: directory-listings.index

   

   Expected (pass)

   • Candidates appear with confidence scores when Find runs successfully
   • Successful unlock creates a primary link for that provider
   • Yelp reviews artifact status updates when the reviews dataset is configured
   • Manual URL lives in the Find listings slide-over (not separate page sections)

   Negative cases (must fail safely)

   • Wrong host / path for that provider → validation error
   • Provider unset → disabled in Find slide-over with not-configured note
   • Incomplete scrape → Failed with unlock refunded

4. Step 4. Recover a lookup that stopped responding

   A confirm starts a background lookup with the directory. If it stops making progress, you no longer have to wait it out or ask an admin. After 30 minutes by default (configurable) the provider is released and the banner turns red with **Try again** — retrying re-uses the listing you originally picked and the confidence it earned, so you do not re-enter the URL. After 120 minutes the request itself is closed out and any reserved unlock is refunded. The longer second window is deliberate: a lookup can simply be queued behind other work, and closing it early would discard a directory result the account already paid for.

   What to do: Local listings → banner reads "… listing did not finish" → Try again

   Where: directory-listings.index

   

   Expected (pass)

   • Stalled lookup renders as a failure (red), never as a green success
   • Try again is offered as soon as the lookup stalls — before the automatic clean-up runs
   • Retry re-submits the original URL; a new lookup starts and the banner returns to in-progress
   • Reserved unlock credits are returned when the request is closed out

   Negative cases (must fail safely)

   • A genuinely in-progress lookup → no Try again, banner stays in-progress with live updates
   • Provider since unconfigured → Try again hidden (nothing to retry into)
   • A live request already holds the provider → retry reports it instead of starting a second lookup

   Tips

   • Recoveries are counted in the hourly operational diagnostics digest, so repeated stalls surface to the team without anyone reporting them.
   • Both windows are configurable: DIRECTORY_LISTINGS_STUCK_AFTER_MINUTES and DIRECTORY_LISTINGS_REAP_AFTER_MINUTES. The reaper never fires before the UI releases the provider.

5. Step 5. Read reputation embeds

   Primary linked listings surface as read-only strips: Business Profile → Directory reputation; Project Settings → Local SEO → Linked directory listings; Project Intelligence → Overview → External proofs. Manage/refresh stays on Local listings.

   What to do: Open Business Profile (ready), Local SEO tab, and Intelligence Overview after linking

   Where: projects.settings.business-profile

   

   Expected (pass)

   • Provider rating / review / complaint counts render when present
   • Stale badges appear when profile or artifact TTLs are exceeded
   • Manage listings links back to Local listings

   Negative cases (must fail safely)

   • Addon off → embeds hidden
   • No primary link → External proofs section omitted

6. Step 6. Unlink, report bad, or refresh

   Unlink removes the project link and remembers a reject so discovery will not re-suggest that listing. Report bad also flags the shared cache row for ops. Refresh profile re-scrapes a stale linked profile and always charges the refresh credit cost. If a refresh comes back incomplete, an already-complete shared profile is left unchanged and the failed refresh is refunded.

   What to do: On a linked row: Unlink, Report bad, or Refresh profile

   Where: directory-listings.index

   

   Expected (pass)

   • Unlink removes the row and flashes confirmation
   • Report bad sets reported_bad on the directory profile (visible in Filament)
   • Refresh queues a new enrichment request when the profile is stale

   Negative cases (must fail safely)

   • Refresh without credits → blocked
   • Foreign link id → 404
   • Refresh already in progress → blocked until the current request finishes

7. Step 7. Admin: enable addon and inspect Directory Profiles

   SuperAdmins enable Local Listings per org in Filament. Shared cache rows (raw JSON, artifacts, org unlocks, project links) live under Filament → Intelligence → Directory Profiles. After empty Find results, open Filament → Intelligence → Discovery Runs for the SERP query, resolved signals, and organic/filtered samples (Yelp today). Scrapes need Horizon on directory-listings (and company-enrichment for Company Intelligence).

   What to do: Filament → Organizations → Add-ons → enable Local Listings. Then Filament → Intelligence → Directory Profiles (or Discovery Runs).

   

   Expected (pass)

   • Pennant override activates directory-listings-addon for that org
   • Tenant sidenav shows Business → Local listings
   • Directory Profiles lists scraped rows after a successful confirm
   • Discovery Runs shows a yelp row after Find with signals and SERP diagnostics

   Negative cases (must fail safely)

   • Toggle off → tenant hits upgrade page
   • Jobs stuck → ensure Horizon supervisor-directory-listings is running; restart after deploy

   Tips

   • Requires BRIGHTDATA_API_TOKEN, BRIGHTDATA_SERP_ZONE, BRIGHTDATA_BBB_COLLECTOR_ID, and ProductionDataSeeder pricing rows for brightdata/dca (and brightdata/dataset for Dataset API providers) under DirectoryListings.
   • BrightData SERP must send a Google search URL (zone + url + format/data_format) — bare `query` bodies fail validation.
   • Optional phase-2 BBB: BRIGHTDATA_BBB_REVIEWS_COLLECTOR_ID and BRIGHTDATA_BBB_COMPLAINTS_COLLECTOR_ID.
   • BBB collector code-mode ↔ API parity: ops runbook in `.claude/tasks/directory-listings-and-company-intelligence-ops.md` §19. Live API still diverges from code-mode while Bright Data support investigates — do not treat matching as production-ready until that checklist passes.
   • Yelp: BRIGHTDATA_YELP_OVERVIEW_DATASET_ID (default gd_lgugwl0519h1p14rwk); optional BRIGHTDATA_YELP_REVIEWS_DATASET_ID=gd_lgzhlu9323u3k24jkv.
   • Angi: BRIGHTDATA_ANGI_PROFILE_COLLECTOR_ID. Trustpilot: BRIGHTDATA_TRUSTPILOT_REVIEWS_DATASET_ID. G2: BRIGHTDATA_G2_OVERVIEW_DATASET_ID.
   • Scheduled artifact refresh is kill-switched by DIRECTORY_LISTINGS_SCHEDULED_REFRESH (default false).