# yelp-fusion

Yelp's Fusion API. Read-only for reviews; Yelp does NOT expose a programmatic API for posting responses, so responses for Yelp are deep-linked to Yelp's own dashboard UI for the operator to paste in.

## What we use

- **Business search:** `GET /v3/businesses/search?term=<name>&location=<addr>` (during onboarding, to match a FranchiseFrontline location to a Yelp business id)
- **Business detail:** `GET /v3/businesses/{id}` (verify the match)
- **Reviews:** `GET /v3/businesses/{id}/reviews` (returns up to 3 most recent reviews on the Fusion plan; the higher-volume Yelp Knowledge plan returns more)

## Reviews caveat

Yelp Fusion's free tier returns only the 3 most recent reviews per business. This is a deliberate Yelp constraint to push businesses to their paid Yelp products. We handle it by:
1. Polling every 10 minutes; the 3 most recent often catches everything that lands in a typical day.
2. Storing every review we see; new reviews appear in the 3-most-recent slot and our dedupe catches them.
3. For brands willing to pay for Yelp Knowledge, we'll add a higher-volume adapter that supports the full review feed.

## Auth

API key in `YELP_API_KEY` environment variable. Bearer token in the `Authorization` header.

## Rate limits

- 5,000 calls per day per API key on Fusion.
- At 10-minute polling per location, one location uses 144 calls/day; safe ceiling is ~30 locations per API key. For more, we shard API keys by tenant.

## Failure modes

- **400 BUSINESS_NOT_FOUND:** the operator's match failed. Show a re-search UI in /app/settings.html.
- **401:** API key revoked. Engineer alert (Brian).
- **429:** back off; respect Yelp's `RateLimit-Reset` header.

## Response posting

Yelp Fusion does NOT support programmatic response posting. The response-drafter still generates the draft; the app surfaces it in the escalation case with a "Copy to Yelp" button and a deep link to `https://biz.yelp.com/login_redirect/...` pointing at the operator's Yelp Business dashboard. Operator pastes and posts manually.

## Compliance

Yelp aggressively flags solicited reviews and "review acquisition" tactics. The respect-platform-tos hook ensures the swarm never suggests an operator solicit reviews and never offers review-gating features.

## Setup steps

1. Operator enters their Yelp business URL in /app/settings.html.
2. We extract the business id from the URL and call business detail to verify.
3. Match confirmed; we start polling.

## Not done in CL-002

The Fusion call code is not yet implemented. Adapter ships in a later CL.