Metadata-Version: 2.4
Name: meta-page-stats
Version: 0.1.0
Summary: Local diagnostic app and CLI for Meta Page insights and post statistics.
Project-URL: Homepage, https://developers.facebook.com/docs/graph-api/reference/insights/
Project-URL: Documentation, https://developers.facebook.com/docs/graph-api/reference/insights/
Keywords: facebook,meta,graph-api,page-insights,analytics
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Office/Business
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.32.0

# Meta Page Stats

Local browser app for retrieving Facebook Page statistics across a selected date range.

The app is intentionally diagnostic-heavy: it identifies whether the token is a User
or Page token, shows which Graph API endpoints were tested, reports metric-by-metric
Page Insights status, and explains Meta permission failures without hiding partial data.
Repeated Graph API responses are cached in server memory for faster reruns. Use the
**Clear cache** button in the browser to discard cached responses.
Long downloads show a progress bar with elapsed time while the synchronous Graph API
request is running.
The **Dark/Light** button switches both the app and chart theme; the choice is saved
in your browser.

## Run

```bash
python3 -m pip install -e .
meta-page-stats --host 127.0.0.1 --port 8000
```

Open `http://127.0.0.1:8000`.

The in-memory cache defaults to 6 hours. Override it before starting the server:

```bash
export META_STATS_CACHE_TTL_SECONDS=900
meta-page-stats
```

You can paste an access token into the app, or set one before starting the server:

```bash
export META_PAGE_ACCESS_TOKEN='EAAB...'
meta-page-stats
```

Do not put your App Secret in this app. The app only needs a User or Page access token.

## App ID and App Secret

You do not enter the App ID or App Secret in the stats UI.

- Use the App ID when selecting your app in Meta's Graph API Explorer or in a Facebook Login flow.
- Keep the App Secret private. It is only for server-side OAuth/token exchange, such as exchanging a short-lived User token for a long-lived token.
- Put the resulting User or Page access token into the app's Access token field.

If "Load pages" says `/me/accounts` does not exist, the token is probably already a Page access token. In that case, enter that Page's numeric ID and run the query directly.

## Meta access

For Page insights and posts, the token normally needs:

- `pages_show_list`
- `pages_read_engagement`
- `read_insights`

If you paste a User token, the app can list pages through `/me/accounts` and resolve the matching Page access token server-side. In Meta development mode, the Facebook user must usually have a role on the Meta app and access to the Page. For production access outside your app roles, Meta may require App Review for the permissions.

To verify a token before using the app, run this in Graph API Explorer with the same token:

```text
GET /PAGE_ID/posts?fields=id,created_time,message&limit=1
GET /PAGE_ID/insights?metric=page_post_engagements&period=day
```

If Graph API Explorer returns `(#10) pages_read_engagement`, regenerate the token and make sure the Facebook permission dialog grants the app access to that specific Page.

If Graph API Explorer also returns `(#10)` for `GET /PAGE_ID/posts?fields=id,created_time,message&limit=1`, the local app cannot make Posts work. That is a Meta permission, Page grant, or App Review issue for `pages_read_engagement` / Page Public Content Access.

If Graph API Explorer returns `(#100) The value must be a valid insights metric`, remove or rename that metric. For Page reactions, use `page_actions_post_reactions_total`; `page_post_reactions_total` is not a valid Graph API metric name. For Page followers, use `page_follows`.

The default Page metric list uses the newer post-November-2025 replacements such as `page_media_view` and `page_follows`, while the Post tab keeps older metrics available too and skips unsupported metrics per post.

In the browser, check:

- **Token diagnostics** for token type, effective Page, endpoint checks, and the next action.
- **Metric statuses** for `ok`, `unsupported`, `no_values`, or `permission_error` per Page metric.
- **Notice** for the plain-English reason when a query returns zero rows.

Official references:

- [Graph API Insights](https://developers.facebook.com/docs/graph-api/reference/insights/)
- [Pages access tokens](https://developers.facebook.com/docs/pages/access-tokens/)
- [Graph API Explorer](https://developers.facebook.com/tools/explorer/)

## CLI export

The CSV exporter is installed as a command:

```bash
meta-page-post-export --page-id 1234567890 --since 2026-04-22 --until 2026-05-19 --out facebook_post_stats.csv
```

The old direct commands `python3 app.py` and `python3 export_meta_page_post_stats.py`
are kept as compatibility launchers for local checkout use. New installs should use
`meta-page-stats` and `meta-page-post-export`.

## Package build

Build and validate the package locally:

```bash
python3 -m pip install build twine
python3 -m build
python3 -m twine check dist/*
```

Upload to TestPyPI when you have credentials configured:

```bash
python3 -m twine upload --repository testpypi dist/*
```

Then test an install from TestPyPI:

```bash
python3 -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ meta-page-stats
meta-page-stats --host 127.0.0.1 --port 8000
```

Do not publish access tokens, App Secrets, cache data, generated CSV exports, or local
screenshots. The package uses a `src/` layout and excludes local build artifacts by
default.
