cli-meta-ads 0.1.0

package/README.md

@@ -0,0 +1,590 @@
+# CLI-meta-ads
+
+Agent-ready CLI for Meta Ads built on top of the Meta Marketing API. The project is designed for safe reads, draft-first mutations, and approval-gated sensitive writes, with a clear separation between CLI entrypoints, config/auth, provider client, domain logic, validators, and output rendering.
+
+## Further documentation
+
+- [Technical documentation](./docs/TECHNICAL.md)
+- [AI agent quick context](./AI_CONTEXT.md)
+- [Claude guide](./CLAUDE.md)
+- [Codex / agents guide](./AGENTS.md)
+- [Bundled skill: `meta-cli-operator`](./skills/meta-cli-operator/SKILL.md)
+- [Requirements snapshot](./REQUIREMENTS.md)
+
+## Status
+
+The CLI is implemented, locally verified, and ready for repo publication and package publication. This repository intentionally does not contain live credentials, a production Meta app setup, or a production approval webhook.
+
+## Installation
+
+### From npm
+
+Global install:
+
+```bash
+npm install -g cli-meta-ads
+meta-ads --help
+```
+
+Without a global install:
+
+```bash
+npx -y cli-meta-ads@latest --help
+```
+
+Notes:
+
+- The package exposes both `meta` and `meta-ads`.
+- `meta-ads` is the safer binary name for shared shells because `meta` is short and can collide with other tools.
+- The examples below use `meta`, but every command can be run as `meta-ads ...`.
+
+### From this repository
+
+```bash
+npm install
+npm run build
+node dist/index.js --help
+```
+
+If you are running directly from the repo, replace `meta ...` in the examples with `node dist/index.js ...`.
+
+Suggested local verification before publishing or releasing:
+
+```bash
+npm run lint
+npm run typecheck
+npm run test
+npm run build
+npm pack --dry-run
+node dist/index.js doctor
+```
+
+## Example specs
+
+Validated example specs are included under [`./examples`](./examples):
+
+- [`./examples/single-object/campaign.json`](./examples/single-object/campaign.json) for `campaigns create`
+- [`./examples/single-object/adset.json`](./examples/single-object/adset.json) for `adsets create`
+- [`./examples/single-object/creative.json`](./examples/single-object/creative.json) for `creatives create`
+- [`./examples/single-object/ad.json`](./examples/single-object/ad.json) for `ads create`
+- [`./examples/launch/multi-format-launch.json`](./examples/launch/multi-format-launch.json) for `launch validate|plan|apply`
+
+Important notes:
+
+- The single-object examples contain placeholder Meta IDs and asset hashes that must be replaced before live use.
+- The launch example demonstrates the current `formats.feed4x5|story9x16` flow and includes tiny placeholder PNGs so `launch validate` works locally out of the box.
+- See [`./examples/README.md`](./examples/README.md) for example commands and usage details.
+
+## Bundled agent skill
+
+The repo and npm package include a bundled operator skill:
+
+- Skill: [`./skills/meta-cli-operator/SKILL.md`](./skills/meta-cli-operator/SKILL.md)
+- OpenAI/Codex descriptor: [`./skills/meta-cli-operator/agents/openai.yaml`](./skills/meta-cli-operator/agents/openai.yaml)
+- Update reference matrix: [`./skills/meta-cli-operator/references/update-matrix.md`](./skills/meta-cli-operator/references/update-matrix.md)
+
+Recommended starting prompt:
+
+```text
+Use $meta-cli-operator to inspect, verify, and operate the Meta Ads CLI safely.
+```
+
+## What the CLI currently covers
+
+- Insights-based performance reads
+- Campaign reads plus approval-gated `pause`, `enable`, and `budget`
+- Campaign, ad set, creative, and ad creation from JSON specs
+- `launch validate|plan|apply|resume` for resumable multi-object runs
+- Ad listing, ad performance, fatigue analysis, and previews
+- Image and video asset uploads, including optional video readiness polling
+- Anomaly detection
+- Pixel visibility and best-effort CAPI visibility
+- Audience listing and size estimates
+- Daily, weekly, and monthly reports
+- Account discovery, default account management, `auth login|logout|status`, `whoami`, `doctor`, and `verify-api`
+- JSON output for agents and automation
+
+## Deliberately out of scope for now
+
+- Carousel, catalog, or dynamic creative flows
+- A direct CAPI event-log API client; `capi` is based on documented pixel/server-event fields
+- Delete, archive, or broader admin workflows
+- Direct ad set budget mutations; `campaigns budget` only works on campaign `daily_budget`
+- Automatic refresh-token handling or a hosted auth broker; the current CLI uses Facebook Login for Business plus a locally stored user token, or a pre-generated token for automation
+
+## Recommended auth model for teams
+
+For an agency or shared internal team, the recommended setup is:
+
+- publish a Meta Business app
+- configure [Facebook Login for Business](https://developers.facebook.com/docs/facebook-login/facebook-login-for-business) for `User access tokens`
+- request the business permissions your app actually needs, such as `ads_read`, `ads_management`, and `business_management`
+- let each operator run `meta auth login`
+
+This keeps permissions user-scoped: the CLI inherits the Business Manager and asset access that the logged-in Meta user already has.
+
+For non-interactive automation, the older pre-generated token path still works and remains useful for server jobs or shared backend processes.
+
+## Setup checklist
+
+These steps must be completed outside the repo for a real production setup.
+
+| Task | Where to do it | Output used by this CLI |
+| --- | --- | --- |
+| Create a Meta app or choose an existing Business app | [Create an app](https://developers.facebook.com/docs/development/create-an-app/), [App Dashboard](https://developers.facebook.com/apps/) | App ID and optional App Secret |
+| Configure Facebook Login for Business for `User access tokens` | [Facebook Login for Business](https://developers.facebook.com/docs/facebook-login/facebook-login-for-business), [Manual login flow](https://developers.facebook.com/docs/facebook-login/guides/advanced/manual-flow) | Login configuration ID and valid redirect URI |
+| Verify app type, permissions, and access requirements | [Authorization](https://developers.facebook.com/docs/marketing-api/get-started/authorization), [Permissions overview](https://developers.facebook.com/docs/permissions), [Ads Management Standard Access](https://developers.facebook.com/docs/features-reference/ads-management-standard-access), [App Review](https://developers.facebook.com/docs/resp-plat-initiatives/individual-processes/app-review) | `ads_read`, optional `ads_management`, feature/review approvals |
+| Add the redirect URI used by the CLI | [Manual login flow](https://developers.facebook.com/docs/facebook-login/guides/advanced/manual-flow) | Valid OAuth redirect URI, for example `https://www.facebook.com/connect/login_success.html` |
+| Optional: create a system user for background automation | [System Users overview](https://developers.facebook.com/docs/business-management-apis/system-users), [Create / retrieve / update](https://developers.facebook.com/docs/business-management-apis/system-users/create-retrieve-update), [Install apps and generate tokens](https://developers.facebook.com/docs/business-management-apis/system-users/install-apps-and-generate-tokens) | `META_ACCESS_TOKEN` for non-interactive jobs |
+| Verify permissions | [ads_read](https://developers.facebook.com/docs/permissions#ads_read), [ads_management](https://developers.facebook.com/docs/permissions#ads_management) | Read and optionally write capabilities |
+| Provide an approval webhook | [n8n Webhook node](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.webhook/) or your own workflow infrastructure | `META_APPROVAL_WEBHOOK` with a production HTTPS URL |
+
+## Values you actually need
+
+### `META_APP_ID`
+
+- Source: [App Dashboard](https://developers.facebook.com/apps/) > App Settings > Basic
+- Required for `meta auth login`
+- Also used by the client when you want `appsecret_proof`
+
+### `META_AUTH_CONFIG_ID`
+
+- Source: [Facebook Login for Business](https://developers.facebook.com/docs/facebook-login/facebook-login-for-business)
+- Required for `meta auth login`
+- This is the configuration ID for the user-token login experience, not an ad account id
+
+### `META_AUTH_REDIRECT_URI`
+
+- Source: [Manual login flow](https://developers.facebook.com/docs/facebook-login/guides/advanced/manual-flow)
+- Optional; defaults to `https://www.facebook.com/connect/login_success.html`
+- If you keep the default, `meta auth login` opens the browser, then asks you to paste the final redirect URL back into the CLI
+- The pasted callback must match this configured redirect URI; mismatched hosts or paths are rejected before the token is stored
+
+### `META_ACCESS_TOKEN`
+
+- Source: either `meta auth login` or [Install apps and generate tokens](https://developers.facebook.com/docs/business-management-apis/system-users/install-apps-and-generate-tokens)
+- Optional if you use `meta auth login`; required if you want to bypass login and inject a token directly
+- Suitable for automation and system-user workflows
+
+### `META_APP_SECRET`
+
+- Source: [App Dashboard](https://developers.facebook.com/apps/) > App Settings > Basic
+- Optional in code; if present, the client automatically computes `appsecret_proof`
+- Only required for `auth login` if your Meta configuration returns an authorization code instead of the default user-token response
+- Meta explicitly warns not to ship the app secret in client-side code or easily decompiled binaries, so it should not be the default team-login path
+
+### `META_APPROVAL_WEBHOOK`
+
+- Source: your workflow/webhook infrastructure, for example n8n or an internal approval service
+- Expected by the code: a valid `https://...` URL
+- Without it, approval-required mutations stay blocked by design
+
+### Ad account IDs
+
+- From the CLI after auth is set up: `meta accounts list`
+- Or from Ads Manager / Business Manager
+- For local convenience afterward: `meta accounts set-default <ad-account-id>`
+
+## Setup by usage mode
+
+### Interactive team login
+
+Recommended for human operators who should inherit their existing Meta Business Manager rights:
+
+```bash
+export META_APP_ID="..."
+export META_AUTH_CONFIG_ID="..."
+export META_CLI_MODE="read"
+
+meta auth login
+```
+
+Optional but useful:
+
+```bash
+export META_DEFAULT_ACCOUNT_ID="1234567890"
+export META_OUTPUT_FORMAT="text"
+export META_API_VERSION="v25.0"
+export META_AUTH_REDIRECT_URI="https://www.facebook.com/connect/login_success.html"
+```
+
+Notes:
+
+- `meta auth login` stores the resulting user token in the local config file with best-effort `0600` file permissions on Unix-like systems.
+- By default the CLI uses Meta's standard user-token flow and does not require the app secret on each operator machine.
+- If `META_ACCESS_TOKEN` is already set in the shell, it still overrides the stored login token.
+
+### Non-interactive automation or system-user setup
+
+Useful for server jobs, shared backend processes, or environments where a human browser login is not appropriate:
+
+```bash
+export META_ACCESS_TOKEN="..."
+export META_CLI_MODE="read"
+```
+
+### Create and upload flows
+
+In addition to either auth setup above:
+
+```bash
+export META_CLI_MODE="write"
+```
+
+Important:
+
+- Mutations still remain drafts until `--apply` is passed explicitly.
+- The current MVP only creates new objects in `PAUSED` status.
+
+### Approval-gated writes
+
+In addition to write mode:
+
+```bash
+export META_APPROVAL_WEBHOOK="https://your-workflow.example/webhook/..."
+```
+
+Required for:
+
+- `campaigns pause`
+- `campaigns enable`
+- `campaigns budget` when the change is greater than `20%`
+
+## Suggested first-time setup in the repo
+
+1. Finish the Meta app and Business setup.
+2. Configure Facebook Login for Business with a `User access token` configuration and note the configuration ID.
+3. Ensure `ads_read`; for write flows also ensure `ads_management` and the correct asset permissions.
+4. Create an approval workflow and expose a production HTTPS webhook URL.
+5. Set your shell environment, for example:
+
+```bash
+export META_APP_ID="..."
+export META_AUTH_CONFIG_ID="..."
+export META_CLI_MODE="read"
+export META_APPROVAL_WEBHOOK="https://your-workflow.example/webhook/..."
+export META_API_VERSION="v25.0"
+```
+
+6. Log in:
+
+```bash
+meta auth login
+```
+
+7. Optionally set a default account:
+
+```bash
+meta accounts set-default 1234567890
+```
+
+8. Verify connectivity:
+
+```bash
+meta auth status
+meta whoami
+meta doctor --account 1234567890
+meta verify-api --account 1234567890
+```
+
+9. Only then start real reads:
+
+```bash
+meta performance --account 1234567890 --last 7d
+meta campaigns list --account 1234567890
+meta pixel status --account 1234567890
+```
+
+## Runtime and config model
+
+### Environment variables
+
+```bash
+META_ACCESS_TOKEN=
+META_APP_ID=
+META_AUTH_CONFIG_ID=
+META_AUTH_REDIRECT_URI=https://www.facebook.com/connect/login_success.html
+META_APP_SECRET=
+META_CLI_MODE=read
+META_APPROVAL_WEBHOOK=
+META_API_VERSION=v25.0
+META_DEFAULT_ACCOUNT_ID=
+META_OUTPUT_FORMAT=text
+```
+
+### Local config file
+
+Path:
+
+```text
+~/.config/cli-meta-ads/config.json
+```
+
+The local config mainly stores:
+
+- `accessToken`
+- `accessTokenExpiresAt`
+- `appId`
+- `authConfigId`
+- `authRedirectUri`
+- `defaultAccountId`
+- `permissionMode`
+- `outputFormat`
+- `apiVersion`
+- optional `approvalWebhook`
+
+### Precedence
+
+1. CLI flags
+2. Environment
+3. Local config
+4. Built-in defaults
+
+Only explicitly set process environment variables are read. The CLI does not auto-load hidden host-local env files such as `~/.claude/meta-ads-env`.
+
+### Debug mode
+
+- `--debug` writes a sanitized runtime summary to `stderr` in text mode
+- in JSON mode the same debug context is embedded under `meta.debug`
+- secrets and sensitive query parameters such as `access_token`, `code`, and `appsecret_proof` are redacted
+
+## Safety model
+
+- Read commands are read-only.
+- Mutation commands stay in draft mode unless `--apply` is passed.
+- `META_CLI_MODE` and `--mode` constrain what is even allowed.
+- Create commands are intentionally limited to `PAUSED` objects and a narrow set of spec types in the current MVP.
+- `campaigns pause` and `campaigns enable` never write directly to Meta; on apply they submit an approval request instead.
+- `campaigns budget` writes directly only when the change is `<= 20%`.
+- Changes above `20%` also go through approval.
+- Without `META_APPROVAL_WEBHOOK`, approval-required writes remain blocked.
+- Approval requests are only sent to HTTPS webhooks.
+- Approval payloads contain only the minimized intended command form, not the full local CLI argv.
+
+## First success path
+
+For the first real credential check, this order is the most reliable:
+
+```bash
+meta auth login
+meta auth status
+meta accounts list
+meta accounts set-default 1234567890
+meta doctor --account 1234567890
+meta verify-api --account 1234567890
+meta performance --account 1234567890 --last 7d
+```
+
+If that works, the read-only setup is usually in good shape.
+
+## Command overview
+
+### Global options
+
+```bash
+meta --json ...
+meta --config /path/to/config.json ...
+meta --api-version v25.0 ...
+meta --mode read|write|admin ...
+meta --apply ...
+```
+
+### Read commands
+
+```bash
+meta auth status
+meta auth logout
+meta performance --account <id|all> --last 7d
+meta performance --account <id|all> --from 2026-03-01 --to 2026-03-09
+
+meta campaigns list --account <id>
+meta campaigns get <campaign-id>
+
+meta ads list --campaign <id>
+meta ads performance --campaign <id> --last 30d --sort ctr
+meta ads fatigue --campaign <id> --last 30d
+meta ads preview <ad-id>
+
+meta anomalies --account <id|all> --threshold 20
+
+meta pixel status --account <id>
+meta pixel events --account <id> --last 24h
+
+meta capi status --account <id>
+meta capi events --account <id> --last 24h
+
+meta audiences list --account <id>
+meta audiences size --audience <id>
+
+meta assets videos status <video-id>
+meta launch validate --account <id> --spec ./launch.json
+meta launch plan --account <id> --spec ./launch.json
+
+meta report daily --account <id>
+meta report weekly --account <id>
+meta report monthly --account <id>
+
+meta accounts list
+meta accounts set-default <id>
+
+meta whoami
+meta doctor [--account <id>]
+meta verify-api [--account <id>]
+```
+
+### Auth commands
+
+```bash
+meta auth login
+meta auth login --app-id <app-id> --config-id <config-id>
+meta auth login --redirect-uri https://www.facebook.com/connect/login_success.html
+meta auth login --no-open-browser
+meta auth status
+meta auth logout
+```
+
+Notes:
+
+- `auth login` opens the browser and then asks for the final redirect URL so the CLI can extract the user access token without requiring a hosted callback service.
+- The pasted callback must resolve to the configured redirect URI; the CLI rejects mismatched callback targets before persisting auth.
+- If your Meta configuration returns an authorization code instead of a user token, `META_APP_SECRET` must be present for the exchange step.
+- `auth logout` clears only the locally stored token; it does not revoke the login inside Meta.
+
+Notes:
+
+- `--account all` is only supported on explicit multi-account read surfaces such as `performance` and `anomalies`.
+- Single-account commands intentionally reject `all`.
+- Relative time windows such as `--last 7d` or `--last 24h` must be positive, and calendar dates are validated strictly as `YYYY-MM-DD`.
+
+### Mutation commands
+
+```bash
+meta assets images upload --account <id> --file ./hero.png
+meta assets videos upload --account <id> --file ./spot.mp4 --wait
+
+meta campaigns create --account <id> --spec ./campaign.json
+meta adsets create --account <id> --spec ./adset.json
+meta creatives create --account <id> --spec ./creative.json
+meta ads create --account <id> --spec ./ad.json
+meta launch apply --account <id> --spec ./launch.json
+meta launch resume --receipt ./.meta-launch/<execution-id>.json
+
+meta campaigns pause <campaign-id>
+meta campaigns enable <campaign-id>
+meta campaigns budget <campaign-id> --daily 120
+
+meta --mode write --apply assets images upload --account <id> --file ./hero.png
+meta --mode write --apply assets videos upload --account <id> --file ./spot.mp4 --wait
+meta --mode write --apply campaigns create --account <id> --spec ./campaign.json
+meta --mode write --apply adsets create --account <id> --spec ./adset.json
+meta --mode write --apply creatives create --account <id> --spec ./creative.json
+meta --mode write --apply ads create --account <id> --spec ./ad.json
+meta --mode write --apply launch apply --account <id> --spec ./launch.json
+meta --mode write --apply launch resume --receipt ./.meta-launch/<execution-id>.json
+meta --mode write --apply campaigns pause <campaign-id>
+meta --mode write --apply campaigns enable <campaign-id>
+meta --mode write --apply campaigns budget <campaign-id> --daily 120
+```
+
+### Create and launch notes
+
+- `campaigns create`, `adsets create`, `creatives create`, and `ads create` read JSON specs via `--spec`.
+- Valid starting points are included in `./examples/single-object/*.json` and `./examples/launch/multi-format-launch.json`.
+- `launch validate` and `launch plan` validate and inspect a full launch spec without writing anything.
+- `launch apply` persists a receipt when `--apply` is used; without `--apply` it only renders the draft plan.
+- `launch resume` continues from a prior receipt; without `--apply` it previews the remaining steps.
+- Asset uploads are also mutations and remain drafts without `--apply`.
+- Videos only poll Meta processing when `--wait` is explicitly set.
+- The current creative MVP supports `link-image` and `video-link`.
+- `campaigns create` supports both non-CBO campaigns and campaign budget optimization via `dailyBudget` or `lifetimeBudget`.
+- `adsets create` derives safe bid-strategy defaults from `bidAmount`.
+- `adsets create` and `launch` normalize Advantage+ Audience age bounds before provider calls when `targeting.targeting_automation.advantage_audience = 1`.
+- `creatives create` supports `formats.feed4x5`, `formats.square1x1`, and `formats.story9x16`, plus the legacy `platformCustomizations.instagram` path for backward compatibility.
+- `launch` compiles placement-aware format slots to Meta `asset_feed_spec` plus `asset_customization_rules` when possible, so one ad can use different files per placement instead of forcing provider cropping.
+- If a `launch` creative uses `formats.*` and also targets placements outside the current abstraction, such as `audience_network.*` or `messenger.sponsored_messages`, `assetRef` is required as the explicit fallback asset.
+- Automatic placements without true format customization generate strong warnings in `launch validate|plan|apply`.
+- Launch receipts default to `./.meta-launch/<execution-id>.json` and can be overridden with `--receipt`.
+
+## Typical workflows
+
+### Read-only operator flow
+
+```bash
+meta auth login
+meta auth status
+meta accounts list
+meta doctor --account 1234567890
+meta verify-api --account 1234567890
+meta report weekly --account 1234567890
+meta anomalies --account 1234567890 --threshold 20
+```
+
+### Create and launch flow
+
+```bash
+meta launch validate --account 1234567890 --spec ./examples/launch/multi-format-launch.json
+meta launch plan --account 1234567890 --spec ./examples/launch/multi-format-launch.json
+meta --mode write --apply launch apply --account 1234567890 --spec ./examples/launch/multi-format-launch.json
+```
+
+### Approval-gated change
+
+```bash
+meta campaigns pause 120000000000000000
+meta --mode write --apply campaigns pause 120000000000000000
+```
+
+Without `--apply` you only see the draft or approval requirement. With `--apply`, the CLI still does not pause directly at Meta; it submits the approval request to the configured HTTPS webhook.
+
+## Known limits
+
+- `capi` is best-effort and not a dedicated CAPI inspector.
+- Multi-account discovery depends on token type, asset permissions, and Meta response shape.
+- Live end-to-end verification against real Meta credentials is intentionally not stored in this repo.
+- The current launch formats abstraction covers feed, search/explore/right-column style surfaces, and story/reels style surfaces; `audience_network.*` and `messenger.sponsored_messages` currently fall back to the explicit base asset and generate warnings.
+- Campaign budget updates fail intentionally if Meta does not expose campaign `daily_budget` for the campaign.
+- Very large list and insights queries fail intentionally after the 100-page safety cap; the CLI does not silently truncate results.
+
+## Publish and release checklist
+
+Before publishing a package or cutting a release:
+
+1. Run `npm run lint`
+2. Run `npm run typecheck`
+3. Run `npm run test`
+4. Run `npm run build`
+5. Run `npm pack --dry-run`
+6. Confirm the tarball does not contain repo-local artifacts or accidental internal files
+7. Re-check `meta --help` or `node dist/index.js --help`
+
+## Verification in the current repo state
+
+```bash
+npm run lint
+npm run typecheck
+npm run test
+npm run build
+npm pack --dry-run
+node dist/index.js --help
+```
+
+## Official source anchors for drift checks
+
+- [Graph API Changelog](https://developers.facebook.com/docs/graph-api/changelog/)
+- [Marketing API overview](https://developers.facebook.com/docs/marketing-api/)
+- [Authorization](https://developers.facebook.com/docs/marketing-api/get-started/authorization)
+- [Facebook Login for Business](https://developers.facebook.com/docs/facebook-login/facebook-login-for-business)
+- [Manually Building the Login Flow](https://developers.facebook.com/docs/facebook-login/guides/advanced/manual-flow)
+- [System Users overview](https://developers.facebook.com/docs/business-management-apis/system-users)
+- [Install apps and generate tokens](https://developers.facebook.com/docs/business-management-apis/system-users/install-apps-and-generate-tokens)
+- [System user permissions guide](https://developers.facebook.com/docs/business-management-apis/system-users/guides/permissions)
+- [Permissions reference](https://developers.facebook.com/docs/permissions)
+- [ads_read](https://developers.facebook.com/docs/permissions#ads_read)
+- [ads_management](https://developers.facebook.com/docs/permissions#ads_management)
+- [Ads Management Standard Access](https://developers.facebook.com/docs/features-reference/ads-management-standard-access)
+- [App Review](https://developers.facebook.com/docs/resp-plat-initiatives/individual-processes/app-review)
+- [Rate limiting](https://developers.facebook.com/docs/graph-api/overview/rate-limiting/)
+- [Insights](https://developers.facebook.com/docs/marketing-api/reference/ad-account/insights/)
+- [Campaigns](https://developers.facebook.com/docs/marketing-api/reference/ad-account/campaigns/)
+- [Ads Pixel](https://developers.facebook.com/docs/marketing-api/reference/ads-pixel/)
+- [Custom Audience](https://developers.facebook.com/docs/marketing-api/reference/custom-audience/)