# Meta services

Stateless API proxy over the **Meta Marketing API** (Facebook / Instagram
advertising), running in AppFactory at `https://services.csbot.cz/apps/meta`.

The service stores no secrets: every credential is supplied per request in an
`X-` header and used only to call the Graph API. Structure mirrors the sibling
`analytics` service.

**Phase 1 is read-only** — every endpoint issues a GET upstream, so the service
cannot spend money. Campaign management is phase 2.

## Quick start

```
GET https://services.csbot.cz/apps/meta/health
GET https://services.csbot.cz/apps/meta/docs      ← Swagger, "Try it out"
```

```bash
curl "https://services.csbot.cz/apps/meta/ads/me/adaccounts" \
  -H "X-Meta-Access-Token: EAAG..." \
  -H "X-Meta-App-Secret: <APP_SECRET>"
```

## Credentials

| Header | Required | Meaning |
| --- | --- | --- |
| `X-Meta-Access-Token` | one of these | Access token; a Business Manager **System User** token is recommended. |
| `Authorization: Bearer <token>` | one of these | Equivalent alternative (the X- header wins if both are sent). |
| `X-Meta-App-Secret` | no, recommended | App secret → the proxy derives `appsecret_proof`. Required if the app enforces app-secret proof. |
| `X-Meta-Api-Version` | no | Graph version override, e.g. `v25.0`. |

Permissions needed for this phase: `ads_read`, `business_management`.

## Endpoints

| Group | Paths |
| --- | --- |
| Infra | `/health`, `/version` |
| Structure | `/ads/me/adaccounts`, `/ads/me/businesses`, `/ads/businesses/{id}/adaccounts`, `/ads/accounts/{id}` (+ `/campaigns`, `/adsets`, `/ads`, `/adcreatives`), `/ads/campaigns/{id}` (+ `/adsets`, `/ads`), `/ads/adsets/{id}` (+ `/ads`), `/ads/ads/{id}`, `/ads/adcreatives/{id}` |
| Insights | `/ads/insights/{object_id}`, `/ads/insights/{object_id}/jobs`, `/ads/insights/{object_id}/run`, `/ads/insights/jobs/{report_run_id}`, `/ads/insights/jobs/{report_run_id}/results` |
| Generic read | `/graph/{path}` |

Large reports must go through the async endpoints — see
[documentation/meta-ads.md](documentation/meta-ads.md).

## Configuration

Non-secret settings come from environment variables; see the table in
[documentation/overview.md](documentation/overview.md). The most relevant one is
`META_API_VERSION` (default `v25.0`), which callers can override per request.

## Local development

```bash
python -m venv .venv
.venv/Scripts/pip install -r requirements.txt
.venv/Scripts/uvicorn app.main:app --reload --port 8000
# http://127.0.0.1:8000/docs
```

## Documentation

- [documentation/overview.md](documentation/overview.md) — architecture, config,
  design decisions, what is deliberately not wired.
- [documentation/meta-ads.md](documentation/meta-ads.md) — endpoints, insight
  fields and levels, pagination, errors, curl examples.