`PLAN.md`

99 lines
# Costa Rica Directory — Plan

**What:** A multi-vertical Costa Rica business directory — tourism + rentals + local services — across all 84 cantones, in the Ventura-Corridor / Ventura-Claw pattern.

**Where:** `~/Projects/costa-rica/` · pm2 process `costa-rica` on `:9791` · standalone PG database `costa_rica_directory` · gated behind HTTP Basic Auth `costarica@agentabrams.com` (password in `secrets-manager` as `COSTARICA_AGENTABRAMS_PASSWORD`).

**Public domain (planned):** `costarica.agentabrams.com` — DNS not yet pointed; deploy step not yet run.

---

## 1. Verticals (16 total)

| Category | Verticals |
|---|---|
| **tourism** | hotel · tour · beach · restaurant · surf |
| **rentals** | short_term · long_term · realestate |
| **service** | food · beauty · retail · fitness · pet · auto · cleaning · creative |

These mirror the Ventura-Claw 8-vertical green list for `service`, plus tourism + rentals on top.

## 2. Regions (33 seeded)

San José · Escazú · Santa Ana · Alajuela · Atenas · Grecia · La Fortuna/Arenal · Heredia · Cartago · Liberia · Tamarindo · Nosara · Santa Teresa · Montezuma · Jacó · Manuel Antonio · Quepos · Uvita · Dominical · Puerto Viejo · Cahuita · Monteverde · Santa Elena · Limón · Puntarenas · Papagayo · Playas del Coco · Flamingo · Sámara · Nicoya · plus 3 catch-all province buckets.

---

## 3. Data sources (ranked by usefulness, per EXA research 2026-05-07)

### 3.1 Government (authoritative)
| Source | Type | Bulk? | Use |
|---|---|---|---|
| **`api.hacienda.go.cr/fe/ae?identificacion={cedula}`** | Lookup-by-cédula | No (rate-limited) | Per-cédula enrichment (situación tributaria + actividades económicas) |
| **MEIC PYMEs Activas (datos.go.cr CKAN)** | XLSX | Yes | National PYME-registered firms list |
| **ICT CST (turismo-sostenible.co.cr)** | HTML scrape | ~130 entities | Tourism vertical seed (hotels, tours, rent-a-car, gastro, spa) |
| **Heredia CKAN — patentes por actividad/distrito** | XLSX | Yes | Heredia cantón ground-truth (pattern for other cantones) |
| **Registro Nacional — Personas Jurídicas** | Search-only | No | Cédula format validation (`3-XXX-XXXXXX`); no bulk export |
| **CGR (Contraloría) RDF/JSON/CSV** | Bulk | Yes (procurement-only) | Government vendors list |

### 3.2 Local / web directories (broad coverage)
- **Google Places API** — Nearby Search around each region's lat/lng (key already in routes.json for the Ad-Signals Rolodex)
- **TripAdvisor** — by town/category (Browserbase headless)
- **Booking.com** — accommodations (Browserbase)
- **Airbnb** — short-term rentals (existing CR pattern from `jill-website` is reference, not source)
- **Yelp Costa Rica** — local services
- **Tico Times classifieds** — `ticotimes.net/classifieds`
- **AM Costa Rica classifieds** — `amcostarica.com`
- **Town-specific portals** — `nosaranow.com`, `tamarindo.com`, `quepos-info.com`, `monteverdeinfo.com`, etc.

### 3.3 Per-cantón patente CKAN (where available)
- Heredia ✅ CKAN
- Most others (Santa Cruz/Tamarindo, Nicoya/Nosara, Aguirre/Manuel Antonio, Garabito/Jacó, Talamanca/Puerto Viejo, San Carlos/La Fortuna, Cóbano/Santa Teresa) require per-cantón check; many are PDF/search-only.
- **Fallback:** Ley 8968 / Ley 8220 transparency request to each municipalidad for patente list.

---

## 4. Ingest pipeline (planned scripts)

```
scripts/ingest/
  _lib.js              # PG upsert, slugify, fetch helpers, region resolver
  ict-cst.js           # ICT sustainable-tourism scrape (~130 rows)
  meic-pymes.js        # CKAN download + parse XLSX
  hacienda-enrich.js   # Per-cédula enrichment via api.hacienda.go.cr
  heredia-patentes.js  # Heredia CKAN download
  google-places.js     # Nearby Search per region centroid
  tripadvisor-cr.js    # Browserbase scrape per town
  booking-cr.js        # Browserbase scrape per town
  local-portals.js     # nosaranow / tamarindo / monteverdeinfo / ticotimes / etc
  run-all.js           # orchestrator → ingest_runs table
```

Each writes to `places` (UPSERT on slug), bumps `ingest_runs`, and respects per-source backoff. None run inside the Express process — they execute via launchd.

## 5. Schedule (planned launchd)

| Job | Frequency | Source |
|---|---|---|
| `com.steve.cr.ict-cst` | weekly Sun 02:00 | ICT CST |
| `com.steve.cr.meic-pymes` | monthly 1st 03:00 | MEIC XLSX |
| `com.steve.cr.google-places` | weekly Mon 03:00 | Google Places |
| `com.steve.cr.local-portals` | daily 04:00 | Web directories |
| `com.steve.cr.hacienda-enrich` | nightly 05:00 | Hacienda (only for `places` w/o `cedula_juridica` → backfill) |

## 6. Compliance / safety rules

- **No headless browser locally** unless Browserbase is unavailable (per MEMORY rule `feedback_browserbase_first`).
- **Respect robots.txt** for every web-directory scrape; rate-limit at 1 req / 2s minimum.
- **No phone-number exfiltration for SMS / DNC scrub**: phone numbers ingested are display-only, not for outreach.
- **No CR DNC list exists nationally** (TCPA is US-only); CR has Ley 8968 (privacy) — display public-record info only, never email-blast scraped owners.
- **Image rule** (per `feedback_no_stock_images`): no Unsplash/Pexels stock; only photos directly from the source listing or public-domain (Wikimedia, Wikicommons CR, etc.).
- **info@ rule**: contact email is `info@agentabrams.com` until `info@<final-domain>` is provisioned.

## 7. Open decisions for Steve

1. Final domain — `costarica.agentabrams.com` (subdomain, fastest) vs. a registered `.cr` / `.com` (longer; needs TLD work).
2. Public vs. gated — is the basic-auth gate temporary (drop when populated) or permanent (admin-only product)?
3. Is `jill-website` (nosarabeachfrontrentals.com) supposed to xref into the Nosara region's `rentals_short` listings, or stay completely independent? (Currently independent per Steve's instruction.)
4. Lead routing — same Stripe-backed `service_*` subscription pattern as Ventura-Claw, or skipped for v1?