Setting up the RevNest connector

What this connector does

The RevNest connector gives Wazzi admins direct, passthrough access to RevNest's NestAPI — the current provider feeding our market-intelligence pipeline for Airbnb and Booking.com listings. Content, reviews, availability, comps with revenue projections, and search-rank subscriptions are all exposed as read-only tools that return the raw provider response.

Nothing on this connector writes to the Wazzi database. The pipeline that fills our centers.market_* and centers.search_rank_* tables runs as DATA SOURCES on the Centers side — one data source per cadence (availability, content & reviews, rank, comps, inventory), each with its own refresh_cron. Day-to-day READ consumers (Owner Center, agents, products) go through the vendor-neutral tools on the Wazzi Data connector (get_market_availability_window, get_comp_set_latest, get_search_rank_daily, etc.) — those tables don't know RevNest exists.

When to use the connector tools directly

• Investigation: "What does RevNest say about THIS listing right now?" — resolve_listing_to_property → get_listing_content / get_listing_reviews / get_listing_availability
• Diagnostics: get_usage (provider's unmetered quota) and get_cost_summary (our ledger by cadence + endpoint)
• Rank enrollment: subscribe_listing_rank — enrol up to 100 Airbnb ids in one unmetered POST
• Market-wide sweep: get_market_listings — paginated inventory around a lat/lon
• Escape hatch: raw_revnest_call for anything not yet typed

---

Vendor-neutral abstraction

Our tables describe the data, not the vendor: market_listing_snapshots, market_availability_nights, market_reviews, market_comp_sets, market_inventory_snapshots, search_rank_daily, etc. Every row carries a source TEXT NOT NULL column (CHECK against 'revnest', 'manual', 'airdna', 'transparent') that tags provenance per row. If we swap or add a provider later, the agent-facing reads keep working — only this connector and the matching sync service change.

---

How the scheduled sync works

Opt-in watch flag

The pipeline only touches units that are explicitly flagged for market tracking. Two boolean columns gate inclusion:

• pms_units.market_data_watch
• pc_prospective_properties.market_data_watch

Both default to false. There is intentionally no UI for these yet — flip them in SQL to add units to the sync, drop them to remove. This lets us ramp carefully one unit at a time.

Mapping anchor rule

Every row in centers.external_listing_mappings MUST link to at least one of pms_unit_id or prospective_property_id (CHECK constraint, enforced in the database). It can link to both when a prospect converts — never neither.

Data-source cadences

Each market-intelligence category is one row in centers.organization_data_source_configs bound to the RevNest connector, with its own refresh_cron. The scheduler sweeps on an external tick (POST /internal/market-intelligence/tick) and runs only configs whose cron is due relative to last_synced_at, each guarded by a per-(org,category) Redis lock.

• market_content_reviews — weekly — ~$0.04 per watched mapping (content + reviews combined)
• market_availability — daily — $0.50 per watched mapping; this is the expensive one, scope the watchlist carefully
• market_rank — daily — ~$0.20 per subscription (RevNest caps active subs at 250 per account); auto-enrolls watched mappings before reading
• market_comps — monthly — $1.50 per watched mapping; the most expensive per call
• market_inventory — monthly — $0.50 per page per geo sweep; one 2-mile sweep per watched unit until an admin UI exposes explicit sweep points

Cost tracking

Every provider call writes a row to centers.market_data_api_usage_log with the endpoint, cadence_tag, HTTP status, duration, response bytes, and estimated USD cost from the rate card baked into the adapter. Use get_cost_summary to roll up spend by cadence and endpoint over a window; it reads our ledger, not RevNest's balance.

There is no cost circuit breaker. Rate limiting is in place (95 req/min with a 0.6s soft floor, 429 retry with Retry-After), but if a sync runs away cost-wise the fix is to narrow the watchlist or widen a cadence, not for the adapter to abort mid-run.

---

Setup — 2 steps, about 2 minutes

Step 1 — Get the OAuth2 credentials from RevNest

RevNest delivers credentials as a one-view link containing a client_id and client_secret pair. Copy both values before closing the link — they're not re-displayable.

Step 2 — Add the connector in Wazzi

1. In the Wazzi Admin Center, go to Connectors
2. Find RevNest in the catalog and click Add
3. Paste the Client ID and Client Secret from Step 1
4. Leave API Base URL blank unless RevNest issued a per-tenant subdomain (default: https://nestapi.revnest.com/v1)
5. Click Test Connection — the health check hits the unmetered /usage/ endpoint
6. Click Save

---

Setup — enabling the scheduled syncs

1. In the Admin Center, go to Centers → Data Sources
2. For each market-intelligence category you want to run, add a data source bound to the RevNest connector:
   • market_availability — e.g. 0 4 * * * (daily at 04:00)
   • market_content_reviews — e.g. 0 5 * * 1 (Mondays at 05:00)
   • market_rank — e.g. 0 6 * * * (daily at 06:00)
   • market_comps — e.g. 0 7 1 * * (1st of month at 07:00)
   • market_inventory — e.g. 0 8 1 * * (1st of month at 08:00)
3. Make sure an external scheduler is calling POST /internal/market-intelligence/tick on a cadence finer than your finest cron (15–30 min is a safe default).
4. Flip market_data_watch = true on one or more pms_units or pc_prospective_properties.

---

First-use runbook — one unit at a time

1. Pick a single unit and get its Airbnb room id (the number in the listing URL) or Booking listing id.
2. From the Wazzi Data MCP: resolve_listing_to_property with that id — proves OAuth, rate limiter, and cost ledger all work.
3. Set market_data_watch = true on the anchor row (SQL).
4. Create a mapping row manually in SQL (or wait for your ingestion flow to create one), anchored to that pms_unit_id or prospective_property_id.
5. Enable the market_content_reviews data source with an aggressive cron (e.g. every 5 minutes) just for the test — it's the cheapest sync.
6. Call /internal/market-intelligence/tick manually (or wait a cycle); confirm rows appear in centers.market_listing_snapshots and centers.market_reviews.
7. Spot-check via the Wazzi Data connector: get_market_listing_latest, get_market_reviews.
8. Enable market_availability, run again, verify 365 nights land in centers.market_availability_nights.
9. Review get_cost_summary — confirm the cadence tags match what ran.
10. Reset the test crons to the recommended cadences, then widen the watchlist.

---

Troubleshooting

Test Connection fails with 503

The default API base is https://nestapi.revnest.com/v1. If an admin pasted https://api.revnest.com or any other host, clear the override and save.

Test Connection fails with 401

Credentials are wrong, or the one-view link was consumed and a different pair was pasted. Request a fresh link from RevNest. The adapter will self-refresh an expired access token once per 401 before giving up.

Test Connection fails with 429

Rate ceiling hit — someone else in the org is driving the adapter. Wait 60 seconds and retry; the limiter releases per-minute.

Sync fills nothing

Confirm market_data_watch = true on the anchor row AND that centers.external_listing_mappings has a row for it. The sync listers only pull mappings whose anchor row is flagged.

Rank sync returns no data

RevNest's crawler visits only after a listing is enrolled in /listing/rank/subscriptions/. The sync auto-enrolls watched mappings, but the first few days of history will show status: NO_RANK_DATA while the crawler fills in — this is correct behaviour, not a bug.

Costs are higher than expected

Run get_cost_summary with the matching window. The breakdown by cadence_tag + endpoint tells you which pipeline is firing. Common causes: a cadence set too aggressively, or the watchlist widened without widening the cadences.