cli-meta-ads 0.1.0

package/AGENTS.md

@@ -0,0 +1,188 @@
+# AGENTS.md
+
+Codex-oriented repo guide for `CLI-meta-ads`.
+
+## Read first
+
+1. `README.md`
+2. `docs/TECHNICAL.md`
+3. `AI_CONTEXT.md`
+4. `src/cli/build-cli.ts`
+5. `src/domain/meta-ads-service.ts`
+6. `CLAUDE.md`
+
+## What exists in this repo
+
+### CLI orchestration
+
+- `src/index.ts`
+- `src/cli/build-cli.ts`
+- `src/cli/context.ts`
+- `src/cli/action.ts`
+
+### Commands
+
+- `src/commands/accounts.ts`
+- `src/commands/assets.ts`
+- `src/commands/performance.ts`
+- `src/commands/campaigns.ts`
+- `src/commands/adsets.ts`
+- `src/commands/creatives.ts`
+- `src/commands/ads.ts`
+- `src/commands/launch.ts`
+- `src/commands/anomalies.ts`
+- `src/commands/pixel.ts`
+- `src/commands/capi.ts`
+- `src/commands/audiences.ts`
+- `src/commands/report.ts`
+- `src/commands/auth.ts`
+- `src/commands/diagnostics.ts`
+
+### Provider/domain internals
+
+- `src/domain/meta-ads-service.ts`
+- `src/domain/launch-service.ts`
+- `src/domain/approval-service.ts`
+- `src/domain/analytics.ts`
+- `src/domain/account-scope.ts`
+- `src/client/meta-api-client.ts`
+- `src/client/meta-discovery.ts`
+
+### Config, validation, output, shared types
+
+- `src/config/file-config.ts`
+- `src/config/types.ts`
+- `src/auth/constants.ts`
+- `src/auth/guards.ts`
+- `src/auth/login.ts`
+- `src/validators/common.ts`
+- `src/validators/create-spec.ts`
+- `src/validators/launch-spec.ts`
+- `src/output/render.ts`
+- `src/utils/errors.ts`
+- `src/utils/date-range.ts`
+- `src/utils/ids.ts`
+- `src/utils/currency.ts`
+- `src/utils/security.ts`
+- `src/types.ts`
+
+### Tests and documentation
+
+- `tests/unit/cli.test.ts`
+- `tests/unit/meta-api-client.test.ts`
+- `tests/unit/analytics.test.ts`
+- `tests/unit/auth-login.test.ts`
+- `tests/unit/approval-service.test.ts`
+- `tests/unit/currency.test.ts`
+- `tests/unit/create-commands.test.ts`
+- `tests/unit/launch.test.ts`
+- `tests/unit/date-range.test.ts`
+- `README.md`
+- `docs/TECHNICAL.md`
+- `AI_CONTEXT.md`
+- `CLAUDE.md`
+- `skills/meta-cli-operator/SKILL.md`
+- `skills/meta-cli-operator/references/update-matrix.md`
+
+## Update rules
+
+If you change CLI behavior, do not stop at code. Update the matching docs and tests in the same pass.
+
+## Guardrails
+
+- `META_APPROVAL_WEBHOOK` must remain HTTPS-only.
+- `--debug` output must stay sanitized and secret-free.
+- Keep the default human auth path on Facebook Login for Business user tokens; do not force operators back onto shared system-user tokens.
+- Only explicit multi-account reads may support `--account all`; single-account commands must reject it.
+- Client pagination safety limits must fail loudly, never truncate silently.
+- Runtime config sources must remain explicit: CLI flags, real process env vars, local config, then defaults. Do not add hidden host-local env-file loading.
+
+### Command tree or command contract changes
+
+Update:
+
+- `src/cli/build-cli.ts`
+- relevant `src/commands/*.ts`
+- relevant tests
+- `README.md`
+- `docs/TECHNICAL.md`
+- `AI_CONTEXT.md`
+- `CLAUDE.md`
+- `skills/meta-cli-operator/SKILL.md` if operator workflow changed
+
+### Validation, flags, args, or input semantics
+
+Update:
+
+- relevant command file
+- `src/validators/common.ts` if shared
+- tests
+- `README.md`
+- `docs/TECHNICAL.md` if behavior/contract changed
+
+### Provider client, API mapping, pagination, retries, auth/discovery behavior
+
+Update:
+
+- `src/domain/meta-ads-service.ts`
+- `src/client/meta-api-client.ts`
+- `src/client/meta-discovery.ts` if relevant
+- tests
+- `docs/TECHNICAL.md`
+- `README.md` if operator-visible
+
+### Approval, draft/write gating, or permission model
+
+Update:
+
+- `src/domain/approval-service.ts`
+- affected `src/commands/*.ts`
+- tests
+- `README.md`
+- `docs/TECHNICAL.md`
+- `AI_CONTEXT.md`
+- `CLAUDE.md`
+- `skills/meta-cli-operator/references/update-matrix.md`
+
+### Config/env/default-path changes
+
+Update:
+
+- `src/config/file-config.ts`
+- `src/cli/context.ts` if runtime context changes
+- tests
+- `README.md`
+- `docs/TECHNICAL.md`
+- `AI_CONTEXT.md`
+- `CLAUDE.md`
+
+### Output or exit-code changes
+
+Update:
+
+- `src/output/render.ts`
+- `src/utils/errors.ts`
+- tests
+- `README.md`
+- `docs/TECHNICAL.md`
+- `AI_CONTEXT.md`
+
+## Skill for operating this repo
+
+Use `skills/meta-cli-operator/` when the task is to run, verify, troubleshoot, or extend the CLI safely.
+
+## Publish sanity checks
+
+- `package.json#files` controls the public npm artifact; keep it aligned with the docs and bundled skill/examples.
+- Run `npm pack --dry-run` before release so repo-local artifacts do not leak into the tarball.
+
+## Verification checklist
+
+```bash
+npm run lint
+npm run typecheck
+npm run test
+npm run build
+npm pack --dry-run
+node dist/index.js --help
+```

package/AI_CONTEXT.md

@@ -0,0 +1,144 @@
+# AI Context: CLI-meta-ads
+
+Purpose: quick, context-sparing overview for AI agents working in this repo.
+
+## What this repo is
+
+- TypeScript CLI for Meta Ads / Marketing API
+- Read-heavy, draft-first, approval-gated for sensitive writes
+- No embedded live credentials
+- Supports Facebook Login for Business user login plus direct token injection
+
+## Entry points
+
+- CLI entry: `src/index.ts`
+- Command tree: `src/cli/build-cli.ts`
+- Main provider service: `src/domain/meta-ads-service.ts`
+- Launch orchestration: `src/domain/launch-service.ts`
+- HTTP client: `src/client/meta-api-client.ts`
+- Approval logic: `src/domain/approval-service.ts`
+- Analytics: `src/domain/analytics.ts`
+
+## Current command surface
+
+- `performance`
+- `assets images upload|videos upload|videos status`
+- `campaigns list|get|create|pause|enable|budget`
+- `adsets create`
+- `creatives create`
+- `ads create|list|performance|fatigue|preview`
+- `launch validate|plan|apply|resume`
+- `anomalies`
+- `pixel status|events`
+- `capi status|events`
+- `audiences list|size`
+- `report daily|weekly|monthly`
+- `accounts list|set-default`
+- `auth login|logout|status`
+- `whoami`
+- `doctor`
+- `verify-api`
+
+## Safety rules
+
+- Reads are read-only.
+- Mutations draft by default.
+- `--apply` is required before any real write attempt.
+- Create/upload commands in the current MVP only support `PAUSED` object creation.
+- `launch apply` and `launch resume` stay draft-only without `--apply`.
+- `campaigns pause` and `campaigns enable` never direct-write; they submit approval when applied.
+- `campaigns budget` direct-writes only when change is `<= 20%`.
+- Approval-gated writes require `META_APPROVAL_WEBHOOK`.
+- `META_APPROVAL_WEBHOOK` must be HTTPS.
+
+## Runtime/config essentials
+
+- Node `>=20`
+- npm package: `cli-meta-ads`
+- published binaries: `meta`, `meta-ads`
+- Build: `npm run build`
+- Verify: `npm run lint && npm run typecheck && npm run test && npm run build && npm pack --dry-run`
+- Config precedence: CLI > env > local config > defaults
+- Local config path: `~/.config/cli-meta-ads/config.json`
+- Env means actual process environment variables only; the CLI does not auto-load hidden host-local env files.
+
+## Required env for real API use
+
+- `META_APP_ID` and `META_AUTH_CONFIG_ID` for `auth login`
+- or `META_ACCESS_TOKEN` for direct token injection / automation
+- optional `META_AUTH_REDIRECT_URI`
+- optional `META_APP_SECRET`
+- `META_CLI_MODE=read|write|admin`
+- optional `META_APPROVAL_WEBHOOK`
+- optional `META_API_VERSION` default `v25.0`
+- optional `META_DEFAULT_ACCOUNT_ID`
+
+## Key implementation facts
+
+- Uses `commander` for CLI and `zod` for validation.
+- Uses direct HTTP against Graph/Marketing API, not a heavy SDK.
+- GETs retry on rate-limit/5xx style failures, including non-JSON error pages; writes do not auto-retry.
+- Error details sanitize secret-bearing request URLs and reflected response previews.
+- Pagination follows Graph cursors and fails loudly above a 100-page safety cap.
+- Account discovery is fallback-based and token-type dependent.
+- `auth login` uses Facebook Login for Business `config_id`, opens the browser, and stores the resulting user token in local config.
+- The default redirect URI is `https://www.facebook.com/connect/login_success.html`; operators paste the final redirect URL back into the CLI so no hosted callback broker is required for the baseline team-login path.
+- The pasted callback must match the configured redirect URI target before the CLI accepts it.
+- If the callback returns an authorization code, the CLI can exchange it only when `META_APP_SECRET` is present.
+- Asset uploads support images directly and videos with readiness polling.
+- Video uploads only poll when `--wait` is set; otherwise the command returns the uploaded video id and leaves follow-up status checks to `assets videos status`.
+- Launch specs support ref-based orchestration with receipt files under `.meta-launch/`.
+- Draft `launch resume` validates the existing receipt and previews the remaining pending steps.
+- Bundled example specs live under `examples/`.
+- Bundled agent skill lives under `skills/meta-cli-operator/`.
+- Campaign create supports classic non-CBO campaigns and campaign budget optimization with explicit campaign budgets.
+- Ad set create supports lead/conversion optimization goals, derives safe bid-strategy defaults from `bidAmount`, and normalizes Advantage+ Audience age bounds before provider calls.
+- CAPI commands are best-effort based on Ads Pixel fields, not a dedicated CAPI endpoint.
+- Campaign budget updates only support campaign-level `daily_budget`.
+- Creative creation supports `link-image` and `video-link` specs, the legacy `platformCustomizations.instagram` override path, and the higher-level slots `formats.feed4x5`, `formats.square1x1`, and `formats.story9x16`.
+- Launch specs additionally support `formats.feed4x5`, `formats.square1x1`, and `formats.story9x16`; launch compiles those slots to Meta `asset_feed_spec` plus `asset_customization_rules` when it needs placement-specific assets in the same ad.
+- `launch validate` now checks placement/format coverage locally and warns hard when automatic placements would otherwise fall back to a single cropped asset.
+- Launch asset paths are resolved relative to the launch spec file, not the process cwd.
+- Relative day windows use local calendar dates and strict date validation.
+- Only explicit multi-account reads support `--account all`; single-account commands reject it.
+- `--debug` writes sanitized runtime context to `stderr` in text mode and embeds it under `meta.debug` in JSON mode.
+- Commander parse failures render JSON when `--json` is requested or JSON output is configured.
+
+## Files to read first
+
+1. `README.md`
+2. `docs/TECHNICAL.md`
+3. `src/cli/build-cli.ts`
+4. `src/domain/meta-ads-service.ts`
+5. `src/client/meta-api-client.ts`
+
+## Open setup tasks outside code
+
+1. Create/configure Meta app
+2. Configure Facebook Login for Business and note the configuration ID
+3. Request permissions/features as needed
+4. Optionally create a system user for automation
+5. Assign ad account/pixel permissions
+6. Provide production approval webhook
+7. Run `auth login`, `doctor`, and `verify-api` with real credentials
+
+## Good extension pattern
+
+- Add validation first
+- Keep command handlers thin
+- Put provider logic in domain/client layers
+- Preserve draft/approval semantics
+- Add tests and update docs
+- Re-check `npm pack --dry-run` when changing published files, docs, examples, or skills
+
+## Official source anchor links
+
+- Marketing API: <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>
+- Manual login flow: <https://developers.facebook.com/docs/facebook-login/guides/advanced/manual-flow>
+- System users: <https://developers.facebook.com/docs/business-management-apis/system-users>
+- Token generation: <https://developers.facebook.com/docs/business-management-apis/system-users/install-apps-and-generate-tokens>
+- Permissions: <https://developers.facebook.com/docs/permissions>
+- 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/>

package/CLAUDE.md

@@ -0,0 +1,183 @@
+# CLAUDE.md
+
+This file explains how to work safely in `CLI-meta-ads` and which files must stay in sync when the CLI changes.
+
+## Start here
+
+Read these files first:
+
+1. `README.md`
+2. `docs/TECHNICAL.md`
+3. `AI_CONTEXT.md`
+4. `src/cli/build-cli.ts`
+5. `src/domain/meta-ads-service.ts`
+6. `AGENTS.md`
+
+## Repository overview
+
+### Runtime and entrypoints
+
+- `src/index.ts`: CLI entrypoint
+- `src/cli/build-cli.ts`: command registration
+- `src/cli/context.ts`: resolved config and command context
+- `src/cli/action.ts`: command execution wrapper, output, exit codes
+
+### Command layer
+
+- `src/commands/accounts.ts`
+- `src/commands/assets.ts`
+- `src/commands/performance.ts`
+- `src/commands/campaigns.ts`
+- `src/commands/adsets.ts`
+- `src/commands/creatives.ts`
+- `src/commands/ads.ts`
+- `src/commands/launch.ts`
+- `src/commands/anomalies.ts`
+- `src/commands/pixel.ts`
+- `src/commands/capi.ts`
+- `src/commands/audiences.ts`
+- `src/commands/report.ts`
+- `src/commands/auth.ts`
+- `src/commands/diagnostics.ts`
+
+### Provider and domain layer
+
+- `src/domain/meta-ads-service.ts`
+- `src/domain/launch-service.ts`
+- `src/domain/approval-service.ts`
+- `src/domain/analytics.ts`
+- `src/domain/account-scope.ts`
+- `src/client/meta-api-client.ts`
+- `src/client/meta-discovery.ts`
+
+### Support layers
+
+- `src/config/file-config.ts`
+- `src/config/types.ts`
+- `src/auth/constants.ts`
+- `src/auth/guards.ts`
+- `src/auth/login.ts`
+- `src/validators/common.ts`
+- `src/validators/create-spec.ts`
+- `src/validators/launch-spec.ts`
+- `src/output/render.ts`
+- `src/utils/errors.ts`
+- `src/utils/date-range.ts`
+- `src/utils/ids.ts`
+- `src/utils/currency.ts`
+- `src/utils/security.ts`
+- `src/types.ts`
+
+### Tests and docs
+
+- `tests/unit/cli.test.ts`
+- `tests/unit/meta-api-client.test.ts`
+- `tests/unit/analytics.test.ts`
+- `tests/unit/auth-login.test.ts`
+- `tests/unit/approval-service.test.ts`
+- `tests/unit/currency.test.ts`
+- `tests/unit/create-commands.test.ts`
+- `tests/unit/launch.test.ts`
+- `tests/unit/date-range.test.ts`
+- `README.md`
+- `docs/TECHNICAL.md`
+- `AI_CONTEXT.md`
+- `AGENTS.md`
+- `skills/meta-cli-operator/SKILL.md`
+- `skills/meta-cli-operator/references/update-matrix.md`
+
+## Operational rules
+
+- Keep reads and writes separate.
+- Keep the default human auth path on Facebook Login for Business user tokens; do not regress to a shared-system-user-only assumption.
+- Preserve draft-first behavior for mutations.
+- Do not remove `--apply` gating.
+- Do not bypass approval-gated flows for `campaigns pause`, `campaigns enable`, or threshold-triggered `campaigns budget`.
+- Prefer changing the smallest coherent layer instead of scattering provider logic into command handlers.
+- Keep `META_APPROVAL_WEBHOOK` HTTPS-only.
+- Keep `--debug` output sanitized; do not print access tokens, appsecret proofs, or raw secret-bearing URLs.
+- Only explicit multi-account commands may accept `--account all`; single-account commands must reject it.
+- Do not silently truncate paginated provider results at the client boundary.
+- Keep runtime config sources explicit: CLI flags, actual process env vars, local config, then defaults. Do not add hidden host-local env-file loading.
+
+## Current create/launch constraints
+
+- Keep create specs `PAUSED`-only unless the repo explicitly broadens that contract.
+- `campaigns create` must keep non-CBO campaign creation provider-safe by sending explicit ad-set budget sharing state when no campaign budget is used.
+- `adsets create` must preserve the bid-strategy defaulting behavior: without `bidAmount`, default to `LOWEST_COST_WITHOUT_CAP`; with `bidAmount`, default to `LOWEST_COST_WITH_BID_CAP`.
+- Advantage+ Audience targeting must be validated or normalized before Meta sees it; current repo behavior normalizes `age_min` down to `25` and `age_max` up to `65` when `targeting.targeting_automation.advantage_audience = 1`.
+- `creatives create` and `launch` both support `formats.feed4x5|square1x1|story9x16`, while the legacy surface `platformCustomizations.instagram` remains for backward compatibility; keep docs and tests aligned if either surface changes.
+
+## Files that must be updated when behavior changes
+
+### If command behavior changes
+
+Update:
+
+- `src/commands/*.ts`
+- `src/cli/build-cli.ts` if registration or command shape changed
+- relevant tests in `tests/unit/`
+- `README.md`
+- `docs/TECHNICAL.md`
+- `AI_CONTEXT.md`
+- `AGENTS.md`
+- `skills/meta-cli-operator/SKILL.md` if the operator workflow changed
+
+### If provider/API behavior changes
+
+Update:
+
+- `src/domain/meta-ads-service.ts`
+- `src/client/meta-api-client.ts`
+- `src/client/meta-discovery.ts` if discovery is affected
+- relevant tests
+- `docs/TECHNICAL.md`
+- `README.md` if users/operators see changed behavior
+
+### If config or env vars change
+
+Update:
+
+- `src/config/file-config.ts`
+- `src/auth/login.ts` if the login bootstrap or redirect handling changes
+- `src/cli/context.ts` if runtime context changed
+- tests
+- `README.md`
+- `docs/TECHNICAL.md`
+- `AI_CONTEXT.md`
+- `AGENTS.md`
+
+### If approval or safety logic changes
+
+Update:
+
+- `src/domain/approval-service.ts`
+- affected command files
+- tests
+- `README.md`
+- `docs/TECHNICAL.md`
+- `AI_CONTEXT.md`
+- `AGENTS.md`
+- `skills/meta-cli-operator/references/update-matrix.md`
+
+### If output or exit codes change
+
+Update:
+
+- `src/output/render.ts`
+- `src/utils/errors.ts`
+- tests
+- `README.md`
+- `docs/TECHNICAL.md`
+- `AI_CONTEXT.md`
+
+## Verification after non-trivial changes
+
+```bash
+npm run lint
+npm run typecheck
+npm run test
+npm run build
+npm pack --dry-run
+node dist/index.js --help
+```