docs(campaigns): document phase 1 campaign management
Records what Phase 1 does and deliberately does not do: no Meta writes, no launch or sync endpoint, previews rendered without creating objects, budget minimums enforced locally, and the fact that a payment method can only be attached in Meta Business Manager. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
@@ -57,6 +57,49 @@ npm run local:import-json # perform the import
|
||||
The import upserts by id and never deletes, so it is safe to re-run. The JSON
|
||||
files are left untouched as a backup.
|
||||
|
||||
## Campaigns
|
||||
|
||||
Campaign records live in PostgreSQL. Apply the schema before first use:
|
||||
|
||||
```powershell
|
||||
npm run local:migrate
|
||||
```
|
||||
|
||||
Set `META_ADS_ACCESS_TOKEN` in Settings > Environments, and enable the
|
||||
`meta_ads` MCP client if you also want campaign tools in chat.
|
||||
|
||||
### What Phase 1 does and does not do
|
||||
|
||||
Phase 1 owns campaign records, the approval workflow, budget guardrails and ad
|
||||
preview. **It creates nothing in Meta.** The only Meta calls are two reads:
|
||||
|
||||
- `GET /act_<id>` for balance, spend and `min_daily_budget`
|
||||
- `GET /act_<id>/generatepreviews` to render ad previews
|
||||
|
||||
There is deliberately no launch or sync endpoint. A campaign moves
|
||||
`draft -> pending_approval -> approved` and stops there; pushing objects to
|
||||
Meta arrives in Phase 2.
|
||||
|
||||
Ad previews are rendered from a creative spec and create no Meta objects, so
|
||||
the wizard can show exactly how an ad will look across desktop feed, mobile
|
||||
feed, Instagram feed, Instagram story, Facebook story and right column before
|
||||
anything exists.
|
||||
|
||||
### Budget minimums
|
||||
|
||||
Each ad account publishes a `min_daily_budget` in minor units. The API rejects
|
||||
a lower daily budget with `422` and a readable message rather than letting Meta
|
||||
reject it opaquely later. If the account cannot be read (no token, rate limit),
|
||||
the check is skipped and a warning is logged: the budget guardrail is not
|
||||
enforced in that case.
|
||||
|
||||
### Delivery requires a payment method
|
||||
|
||||
Meta will not deliver ads until a funding source is attached to the ad account.
|
||||
**This cannot be done from MaskanX** — the Marketing API does not allow
|
||||
creating funding instruments, so it must be done in Meta Business Manager. The
|
||||
Campaigns page shows a warning when no payment method is present.
|
||||
|
||||
### Clearing and restoring credentials
|
||||
|
||||
**Stop MaskanX before clearing credentials.** A running app holds its
|
||||
|
||||
Reference in New Issue
Block a user