# Cloudbeds Parsing Upgrade Plan

## Goal

Move from link-only / partial daily reporting to actual parsed Cloudbeds occupancy metrics.

## Current proven state

Working now:
- Gmail readonly search
- latest Cloudbeds occupancy email discovery
- link extraction
- short-link resolution
- tokenized Data Insights page discovery
- internal report API path discovery from frontend JS

Known blocker:
- direct backend fetch to the report task endpoint returns `401 Unauthorized`

## What this means

The final Cloudbeds data likely requires one of:
- browser-executed fetches with session/browser context
- cookies or dynamic headers generated by the frontend runtime
- token handoff logic inside the app that is not satisfied by raw HTTP fetch

## Recommended next technical step

Use a browser-capable local workflow to:
1. open the tokenized report URL
2. let the frontend JS load
3. capture network calls or rendered download link(s)
4. identify the real downloadable payload or rendered data source
5. parse the resulting file/data into structured occupancy metrics

## Best implementation options

### Option A — Playwright/Puppeteer style browser extraction
Best for reliability.

### Option B — Safari/WebKit automation with network observation
Possible, but less clean.

### Option C — reverse-engineer the exact Cloudbeds API auth pattern
Possible, but usually slower and more brittle.

## Why browser automation is likely best

The Cloudbeds report page is a client-side JS app. The frontend already knows how to retrieve the report. Browser automation lets us follow the same successful path rather than guessing headers/auth manually.

## Desired end state

Daily script should eventually return:
- property occupancy table
- portfolio occupancy totals
- trend versus yesterday
- notable changes or anomalies
- concise executive summary for Bill

## Near-term reality

Until this upgrade is added, the daily report should remain honest and useful by reporting:
- latest report freshness
- retrieval status
- direct link
- any delivery anomalies