cli-meta-ads 0.1.0

package/docs/TECHNICAL.md

@@ -0,0 +1,480 @@
+# CLI-meta-ads Technical Documentation
+
+## Purpose
+
+This document is the maintainer-facing technical reference for the CLI. It explains architecture, command orchestration, safety rules, provider boundaries, output contracts, tests and extension points.
+
+For a short AI-oriented summary, use [../AI_CONTEXT.md](../AI_CONTEXT.md).
+
+## Runtime and Tooling
+
+- Language: TypeScript
+- Runtime: Node.js `>=20`
+- Module format: ESM
+- CLI parser: `commander`
+- Validation: `zod`
+- Tests: `vitest`
+- Lint: `eslint`
+- Build: `tsc -p tsconfig.build.json`
+
+## Distribution Surface
+
+- npm package name: `cli-meta-ads`
+- published binaries: `meta` and `meta-ads`
+- recommended global binary for end users: `meta-ads`
+- package allow-list is controlled via `package.json#files`
+- the published artifact is intended to include:
+  - compiled CLI in `dist/`
+  - operator docs (`README.md`, `docs/TECHNICAL.md`, `AI_CONTEXT.md`, `AGENTS.md`, `CLAUDE.md`)
+  - example specs in `examples/`
+  - the bundled agent skill in `skills/meta-cli-operator/`
+
+Run `npm pack --dry-run` before release so the tarball stays free of repo-local artifacts, tests, and accidental internal files.
+
+## Repository Layout
+
+```text
+src/
+  auth/
+  cli/
+  client/
+  commands/
+  config/
+  domain/
+  output/
+  utils/
+  validators/
+examples/
+  launch/
+  single-object/
+tests/
+  unit/
+docs/
+```
+
+### Key files
+
+- `src/index.ts`: process entrypoint
+- `src/cli/build-cli.ts`: top-level command tree
+- `src/cli/context.ts`: config resolution and per-command runtime context
+- `src/client/meta-api-client.ts`: HTTP client, retries, pagination, usage headers, error mapping
+- `src/client/meta-discovery.ts`: account discovery fallbacks
+- `src/domain/meta-ads-service.ts`: Meta API operations and response normalization
+- `src/domain/launch-service.ts`: launch planning, receipts, resumable execution
+- `src/domain/approval-service.ts`: approval policy and webhook submission
+- `src/domain/analytics.ts`: anomalies, summaries, fatigue heuristics
+- `src/output/render.ts`: text and JSON rendering
+- `src/utils/errors.ts`: stable exit codes and typed app/provider errors
+- `examples/`: operator-ready example specs kept in sync with the current validators
+- `tests/unit/example-specs.test.ts`: validates bundled example specs against the real schemas
+
+## Execution Flow
+
+1. `src/index.ts` calls `runCli`.
+2. `runCli` builds the command tree in `src/cli/build-cli.ts`.
+3. Each command action is wrapped by `createAction` in `src/cli/action.ts`.
+4. `createAction` resolves config and runtime context via `createCommandContext`.
+5. The command handler calls domain services.
+6. Domain services call the Meta client.
+7. Results are rendered via `src/output/render.ts`.
+8. Errors are converted to stable output and exit codes.
+
+## Config and Auth Model
+
+### Inputs
+
+- CLI flags
+- environment variables
+- local config file `~/.config/cli-meta-ads/config.json`
+
+Only explicit process environment variables are read. The CLI does not auto-load host-local env files outside the documented config path.
+
+### Resolved config
+
+The resolved config includes:
+
+- `accessToken`
+- `accessTokenExpiresAt`
+- `appId`
+- `appSecret`
+- `authConfigId`
+- `authRedirectUri`
+- `apiVersion`
+- `permissionMode`
+- `approvalWebhook`
+- `defaultAccountId`
+- `outputFormat`
+
+### Precedence
+
+`CLI > env > config file > defaults`
+
+### Auth expectations
+
+- The CLI supports two auth sources:
+  - a locally persisted user token from `auth login`
+  - a pre-generated token provided directly via `META_ACCESS_TOKEN`
+- For human operators, the intended path is [Facebook Login for Business](https://developers.facebook.com/docs/facebook-login/facebook-login-for-business) with a `User access token` configuration.
+- `auth login` opens the browser, drives the Meta login flow via `config_id`, and then asks the operator to paste the final redirect URL back into the CLI.
+- The pasted callback must match the configured `authRedirectUri` target before the CLI accepts the token or auth code.
+- The default redirect URI is `https://www.facebook.com/connect/login_success.html`, which avoids requiring a local callback server or hosted broker for the baseline team-login flow.
+- If the callback returns an authorization code instead of a token, the CLI can exchange it only when `META_APP_SECRET` is present. This is intentionally not the default team-login path because Meta warns not to distribute app secrets in client-side code or easily decompiled binaries.
+- Env still wins over persisted auth. If `META_ACCESS_TOKEN` is set, it overrides the stored login token for the current process.
+
+### Debug behavior
+
+`--debug` writes a sanitized runtime summary to `stderr` in text mode.
+In JSON mode the same payload is embedded under `meta.debug` so machine consumers still receive one parseable JSON document per stream.
+
+It is intentionally limited to:
+
+- resolved non-secret config
+- sanitized argv
+- boolean presence flags for secrets/webhooks
+
+## Safety and Mutation Model
+
+### Permission level
+
+Configured via `META_CLI_MODE` or `--mode`:
+
+- `read`
+- `write`
+- `admin`
+
+### Draft vs write
+
+- Read commands always read.
+- Mutation commands default to draft.
+- `--apply` is required for any actual write attempt.
+- Asset uploads and create commands are mutations and therefore also stay in draft mode without `--apply`.
+- `launch apply` and `launch resume` follow the same rule: without `--apply`, they only render a plan/preview.
+- Draft `launch resume` still opens and validates the existing receipt so the preview reflects the real pending state.
+
+### Approval policy
+
+- `campaigns pause`: always approval-gated
+- `campaigns enable`: always approval-gated
+- `campaigns budget`: direct write only when change is `<= 20%`
+- create/upload MVP: direct write only for explicitly applied `PAUSED` object creation and asset upload
+- Approval-gated actions do not write to Meta. They submit a webhook payload instead.
+
+### Create-flow MVP boundaries
+
+The current create surface is intentionally narrow:
+
+- `campaigns create`, `adsets create`, `creatives create`, and `ads create` accept JSON specs via `--spec`
+- `launch validate|plan|apply|resume` orchestrates the same object subset behind a single launch spec plus receipt file
+- object creation is limited to `PAUSED` status in the MVP
+- campaign create supports both non-CBO campaigns and campaign budget optimization via `dailyBudget` or `lifetimeBudget`; non-CBO requests explicitly send the provider flag that keeps ad-set budgeting enabled, and campaign-level `bidStrategy` is only valid with campaign budgets
+- ad set create supports additional lead/conversion `optimizationGoal` values such as `OFFSITE_CONVERSIONS`, `LEAD_GENERATION`, `QUALITY_LEAD`, `CONVERSATIONS`, and `VALUE`
+- ad set create derives a provider-safe default `bid_strategy` when one is not supplied: `LOWEST_COST_WITHOUT_CAP` without `bidAmount`, `LOWEST_COST_WITH_BID_CAP` with `bidAmount`
+- Advantage+ Audience requests are normalized before the provider call when `targeting.targeting_automation.advantage_audience = 1`: `age_min` is capped at `25` and `age_max` is raised to at least `65`
+- supported creative kinds are `link-image` and `video-link`
+- `creatives create` supports both the legacy override path `platformCustomizations.instagram` and the higher-level format slots `formats.feed4x5`, `formats.square1x1`, and `formats.story9x16`
+- images upload directly; videos are only polled until ready when `--wait` is requested, otherwise the upload returns the created video id and leaves status checks to `assets videos status`
+- launch asset file paths are resolved relative to the launch spec location
+- launch creatives additionally support `formats.feed4x5`, `formats.square1x1`, and `formats.story9x16`
+- launch compiles those format slots into Meta `asset_feed_spec` plus `asset_customization_rules` when multiple placement-specific assets are required; otherwise it falls back to the existing simple creative create path
+- `creatives create` uses the same asset-feed compiler, but with canonical placement groups because it does not have ad-set targeting context available at create time
+- when launch formats are used alongside placements outside the current abstraction, such as `audience_network.*` or `messenger.sponsored_messages`, `assetRef` remains mandatory as the explicit fallback asset
+- launch receipts default to `.meta-launch/<executionId>.json` and support resumable retries
+- `launch validate` remains local-only, but it now validates placement/format coverage, checks spec-relative asset files, and emits warnings for automatic placements without real format customization; it still does not execute a remote Meta `validate_only` preflight
+- placements outside the current format abstraction, especially `audience_network.*` and `messenger.sponsored_messages`, fall back to the creative's default asset and produce warnings
+
+### Approval transport
+
+`src/domain/approval-service.ts` sends a JSON payload to `META_APPROVAL_WEBHOOK`.
+
+The webhook must be a valid `https://...` URL. Non-HTTPS or invalid URLs are rejected during config resolution and again at submission time as a defense-in-depth check.
+
+The payload includes:
+
+- action
+- resource type and id
+- account id
+- requested mode
+- minimized argv
+- change summary
+- reason
+- timestamp
+
+The approval payload intentionally does not forward the raw local CLI argv such as `--config /path/to/file`.
+
+## Command Tree and Module Mapping
+
+| Command | Module | Primary provider surface | Mode |
+| --- | --- | --- | --- |
+| `assets images upload` | `src/commands/assets.ts` | ad account adimages edge | draft / write |
+| `assets videos upload/status` | `src/commands/assets.ts` | ad account advideos edge / video node | draft / write / read |
+| `performance` | `src/commands/performance.ts` | Insights API | read |
+| `campaigns list/get/create` | `src/commands/campaigns.ts` | Campaign node / campaigns edge | read / draft / write |
+| `adsets create` | `src/commands/adsets.ts` | Ad set create edge | draft / write |
+| `creatives create` | `src/commands/creatives.ts` | Ad creative create edge | draft / write |
+| `ads create` | `src/commands/ads.ts` | Ad create edge | draft / write |
+| `launch validate/plan/apply/resume` | `src/commands/launch.ts` | launch orchestration over campaign/ad set/asset/creative/ad edges | read / draft / write |
+| `campaigns pause/enable/budget` | `src/commands/campaigns.ts` | Campaign node updates | draft / approval / write |
+| `ads list` | `src/commands/ads.ts` | Campaign ads edge | read |
+| `ads performance` | `src/commands/ads.ts` | Insights API level=ad | read |
+| `ads fatigue` | `src/commands/ads.ts` | Insights API + local analytics | read |
+| `ads preview` | `src/commands/ads.ts` | Ad previews edge | read |
+| `anomalies` | `src/commands/anomalies.ts` | Insights API + local analytics | read |
+| `pixel status/events` | `src/commands/pixel.ts` | Ad account pixels / pixel fields | read |
+| `capi status/events` | `src/commands/capi.ts` | Pixel/server-event related fields | read |
+| `audiences list/size` | `src/commands/audiences.ts` | Custom audiences | read |
+| `report *` | `src/commands/report.ts` | Insights API + summary | read |
+| `accounts list/set-default` | `src/commands/accounts.ts` | discovery + local config | read / local write |
+| `auth login/logout/status` | `src/commands/auth.ts` | local config + Facebook Login for Business bootstrap + `/me` probe | local auth / read |
+| `whoami`, `doctor`, `verify-api` | `src/commands/diagnostics.ts` | `/me`, account, campaigns, insights | read / verify |
+
+## Meta Client Design
+
+### Responsibilities
+
+`src/client/meta-api-client.ts` owns:
+
+- request construction
+- access token attachment
+- optional `appsecret_proof`
+- multipart upload requests for asset ingestion
+- GET retry policy
+- rate limit header extraction
+- provider error parsing
+- pagination via cursor-following
+
+### Retry policy
+
+Automatic retries exist only for safe GET requests.
+
+Retriable classes:
+
+- HTTP `429`
+- HTTP `5xx`
+- selected Meta rate-limit codes such as `4`, `17`, `32`, `341`, `613`, `80001`, `80002`, `80004`
+
+Mutation requests are intentionally not retried automatically.
+
+Non-JSON provider responses are converted into `MetaApiError` instances so retriable `429`/`5xx` paths still participate in the retry policy, and any request URL or response preview included in error details is sanitized.
+
+### Pagination
+
+Pagination uses `paging.cursors.after` and reissues the same path with `after=...`.
+
+This avoids relying on opaque `paging.next` URLs alone.
+
+There is a hard safety cap of 100 pages. If the cap is exceeded, the client fails loudly instead of returning silently truncated data.
+
+### Rate limit visibility
+
+The client parses these headers when present:
+
+- `X-App-Usage`
+- `X-Ad-Account-Usage`
+- `X-Business-Use-Case-Usage`
+
+## Account Discovery
+
+Account discovery is intentionally layered because Meta token behavior differs by token type and asset wiring.
+
+Current fallback chain in `src/client/meta-discovery.ts`:
+
+1. `/me/adaccounts`
+2. `/me?fields=assigned_ad_accounts{...}`
+3. `/me/businesses`
+4. per business expansion for owned/client ad accounts
+
+This is a best-effort strategy, not a guarantee.
+
+The top-level discovery probes are run in parallel where possible, while per-business expansion stays sequential to avoid request bursts. Auth and rate-limit failures are not swallowed, because returning a partial account set would be misleading.
+
+## Domain Service Design
+
+`src/domain/meta-ads-service.ts` is the main provider-facing service.
+
+It is responsible for:
+
+- campaign/ad set/creative/ad creation
+- image and video uploads
+- campaign reads and writes
+- ad listing and previews
+- insights retrieval
+- pixel listing
+- audience listing
+- verification calls
+- response normalization through `zod`
+
+`src/domain/launch-service.ts` is the orchestration layer for multi-step creation.
+
+It is responsible for:
+
+- validating the ordered launch plan against the normalized launch spec
+- persisting receipts before and after each step
+- resuming incomplete runs from receipt state
+- sequencing asset upload, video wait, and dependent object creation
+
+`src/domain/analytics.ts` is intentionally local-only and contains no provider logic.
+
+It calculates:
+
+- performance summaries
+- anomalies
+- fatigue scores
+- report summaries
+
+## Validation Strategy
+
+### CLI boundary
+
+`src/validators/common.ts` validates:
+
+- account selections
+- campaign/ad/audience ids
+- positive numeric inputs
+- threshold inputs
+- allowed breakdowns
+
+`src/utils/date-range.ts` additionally enforces:
+
+- positive relative windows only
+- strict calendar-date validation for `YYYY-MM-DD`
+- local-calendar semantics for relative day windows
+
+Single-account commands reject `--account all` before any provider call is made.
+
+`src/validators/create-spec.ts` validates the current create MVP specs, enforces promoted-object requirements for key lead/conversion goals, normalizes Advantage+ targeting ages, and validates both legacy Instagram overrides and the direct creative format slots `formats.feed4x5|square1x1|story9x16`.
+`src/validators/launch-spec.ts` validates the launch manifest, ref integrity, spec-relative asset files, placement/format compatibility for `formats.feed4x5|square1x1|story9x16`, and the additional creative asset refs used by either launch formats or legacy `platformCustomizations.instagram`.
+
+### Provider boundary
+
+`src/domain/meta-ads-service.ts` validates critical provider responses with `zod` and normalizes them into internal structures.
+
+The schemas are intentionally partial and `.passthrough()` to remain resilient to additive provider changes.
+
+## Output Contract
+
+All command handlers return a structured result:
+
+```ts
+{
+  ok: true,
+  command: string,
+  data: unknown,
+  warnings?: string[],
+  meta?: Record<string, unknown>,
+  partialFailures?: { scope: string; message: string }[]
+}
+```
+
+Rendering modes:
+
+- text (default)
+- JSON (`--json`)
+
+`src/output/render.ts` renders flat arrays as tables when possible.
+
+Commander/parse failures are also rendered as JSON failures when `--json` is present or `outputFormat=json` is configured, so automation does not need to special-case parser errors.
+
+## Exit Codes
+
+Defined in `src/utils/errors.ts`.
+
+Important codes:
+
+- `0`: success
+- `2`: usage error
+- `3`: config error
+- `4`: auth error
+- `5`: permission error
+- `6`: rate limit
+- `7`: provider/runtime error
+- `8`: partial failure
+- `9`: approval required/submitted
+- `10`: unsafe operation blocked
+- `11`: verification/setup failure
+
+## Testing
+
+Current automated coverage:
+
+- auth login flow and optional auth-code exchange
+- Meta client retries
+- Meta pagination
+- account discovery fallback
+- file-config precedence and persistence
+- CLI draft flow for campaign pause
+- CLI direct budget write below threshold
+- CLI approval flow above threshold
+- create and asset command flows
+- launch validation, planning, receipts, and resume flows
+- bundled example spec validation
+
+Test files:
+
+- `tests/unit/analytics.test.ts`
+- `tests/unit/auth-login.test.ts`
+- `tests/unit/approval-service.test.ts`
+- `tests/unit/currency.test.ts`
+- `tests/unit/date-range.test.ts`
+- `tests/unit/meta-api-client.test.ts`
+- `tests/unit/cli.test.ts`
+- `tests/unit/file-config.test.ts`
+- `tests/unit/create-commands.test.ts`
+- `tests/unit/launch.test.ts`
+- `tests/unit/example-specs.test.ts`
+
+The tests use fetch injection and do not require live Meta credentials.
+
+## Build and Verification
+
+```bash
+npm run lint
+npm run typecheck
+npm run test
+npm run build
+npm pack --dry-run
+node dist/index.js --help
+```
+
+## Known Constraints
+
+- `doctor` and `verify-api` are the intended live verification path; this repo does not embed credentials.
+- `capi` commands are best-effort and intentionally conservative in their wording.
+- `campaigns budget` will block if the campaign does not expose campaign-level `daily_budget`.
+- No `.env` loader is built in.
+- Stored user tokens are not refreshed automatically; operators should rerun `auth login` when a token expires.
+
+## Extending the CLI
+
+When adding a new command:
+
+1. Add validation in `src/validators` or command-local parsing.
+2. Add or extend domain logic in `src/domain`.
+3. Add provider calls in `src/client` or `src/domain/meta-ads-service.ts`, not in command handlers.
+4. Register the command in `src/cli/build-cli.ts`.
+5. Add tests for parse, happy path and failure path.
+6. Update [../README.md](../README.md) and [../AI_CONTEXT.md](../AI_CONTEXT.md).
+
+## Practical Next Engineering Steps
+
+1. Add CI for `lint`, `typecheck`, `test`, `build`.
+2. Add optional smoke tests for `doctor` / `verify-api` in a protected environment.
+3. Decide whether `.env` loading is desired or whether shell-export-only remains the standard.
+4. Keep package metadata and `package.json#files` aligned with the documented release surface.
+5. Expand write coverage only if the same draft/approval discipline is preserved.
+
+## Official Source Set
+
+- [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](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/)
+- [Graph API changelog](https://developers.facebook.com/docs/graph-api/changelog/)

package/examples/README.md

@@ -0,0 +1,29 @@
+# Example Specs
+
+This directory contains copy-paste-ready example specs for the current CLI contract.
+
+## Included examples
+
+- `single-object/campaign.json`: example input for `campaigns create`
+- `single-object/adset.json`: example input for `adsets create`
+- `single-object/creative.json`: example input for `creatives create`
+- `single-object/ad.json`: example input for `ads create`
+- `launch/multi-format-launch.json`: end-to-end launch example with placement-aware creative formats
+
+## Important notes
+
+- Replace placeholder Meta IDs such as page, campaign, ad set, and creative IDs before live use.
+- Replace placeholder asset hashes in `single-object/creative.json` after running `assets images upload`.
+- `launch/assets/*.png` are tiny placeholder images committed only so `launch validate` works out of the box. Replace them with real production assets before `launch apply`.
+
+## Useful commands
+
+```bash
+node dist/index.js launch validate --account 1234567890 --spec ./examples/launch/multi-format-launch.json
+node dist/index.js launch plan --account 1234567890 --spec ./examples/launch/multi-format-launch.json
+
+node dist/index.js --json campaigns create --account 1234567890 --spec ./examples/single-object/campaign.json
+node dist/index.js --json adsets create --account 1234567890 --spec ./examples/single-object/adset.json
+node dist/index.js --json creatives create --account 1234567890 --spec ./examples/single-object/creative.json
+node dist/index.js --json ads create --account 1234567890 --spec ./examples/single-object/ad.json
+```

package/examples/launch/multi-format-launch.json

@@ -0,0 +1,90 @@
+{
+  "version": 1,
+  "campaign": {
+    "ref": "campaign.spring-sale",
+    "name": "Spring Sale - Prospecting",
+    "objective": "OUTCOME_TRAFFIC",
+    "specialAdCategories": [],
+    "status": "PAUSED"
+  },
+  "adSets": [
+    {
+      "ref": "adset.prospecting.feed-story",
+      "campaignRef": "campaign.spring-sale",
+      "name": "Prospecting - DE - Feed + Story",
+      "billingEvent": "IMPRESSIONS",
+      "optimizationGoal": "LINK_CLICKS",
+      "dailyBudget": 5000,
+      "promotedObject": {
+        "pageId": "1234567890"
+      },
+      "targeting": {
+        "geo_locations": {
+          "countries": [
+            "DE"
+          ]
+        },
+        "publisher_platforms": [
+          "facebook",
+          "instagram"
+        ],
+        "facebook_positions": [
+          "feed"
+        ],
+        "instagram_positions": [
+          "stream",
+          "story",
+          "reels"
+        ]
+      },
+      "status": "PAUSED"
+    }
+  ],
+  "assets": [
+    {
+      "ref": "asset.feed4x5",
+      "kind": "image",
+      "file": "./assets/feed4x5.png",
+      "name": "Spring Sale Feed 4x5"
+    },
+    {
+      "ref": "asset.story9x16",
+      "kind": "image",
+      "file": "./assets/story9x16.png",
+      "name": "Spring Sale Story 9x16"
+    }
+  ],
+  "creatives": [
+    {
+      "ref": "creative.spring-sale",
+      "kind": "link-image",
+      "name": "Spring Sale Creative",
+      "pageId": "1234567890",
+      "formats": {
+        "feed4x5": {
+          "assetRef": "asset.feed4x5"
+        },
+        "story9x16": {
+          "assetRef": "asset.story9x16"
+        }
+      },
+      "linkData": {
+        "link": "https://example.com/spring-sale",
+        "message": "Spring Sale live now. Discover the new collection.",
+        "headline": "Spring Sale",
+        "description": "Limited-time offer",
+        "callToAction": "SHOP_NOW"
+      },
+      "status": "PAUSED"
+    }
+  ],
+  "ads": [
+    {
+      "ref": "ad.spring-sale.01",
+      "name": "Spring Sale - Ad 01",
+      "adSetRef": "adset.prospecting.feed-story",
+      "creativeRef": "creative.spring-sale",
+      "status": "PAUSED"
+    }
+  ]
+}

package/examples/single-object/ad.json

@@ -0,0 +1,6 @@
+{
+  "name": "Spring Sale - Ad 01",
+  "adSetId": "1234567890",
+  "creativeId": "1234567890",
+  "status": "PAUSED"
+}

package/examples/single-object/adset.json

@@ -0,0 +1,30 @@
+{
+  "campaignId": "1234567890",
+  "name": "Prospecting - DE - Feed + Story",
+  "billingEvent": "IMPRESSIONS",
+  "optimizationGoal": "LINK_CLICKS",
+  "dailyBudget": 5000,
+  "promotedObject": {
+    "pageId": "1234567890"
+  },
+  "targeting": {
+    "geo_locations": {
+      "countries": [
+        "DE"
+      ]
+    },
+    "publisher_platforms": [
+      "facebook",
+      "instagram"
+    ],
+    "facebook_positions": [
+      "feed"
+    ],
+    "instagram_positions": [
+      "stream",
+      "story",
+      "reels"
+    ]
+  },
+  "status": "PAUSED"
+}

package/examples/single-object/campaign.json

@@ -0,0 +1,6 @@
+{
+  "name": "Spring Sale - Prospecting",
+  "objective": "OUTCOME_TRAFFIC",
+  "specialAdCategories": [],
+  "status": "PAUSED"
+}

package/examples/single-object/creative.json

@@ -0,0 +1,19 @@
+{
+  "kind": "link-image",
+  "name": "Spring Sale - Multi-Format Creative",
+  "pageId": "1234567890",
+  "imageHash": "img_hash_feed4x5_replace_me",
+  "formats": {
+    "story9x16": {
+      "imageHash": "img_hash_story9x16_replace_me"
+    }
+  },
+  "linkData": {
+    "link": "https://example.com/spring-sale",
+    "message": "Spring Sale live now. Discover the new collection.",
+    "headline": "Spring Sale",
+    "description": "Limited-time offer",
+    "callToAction": "SHOP_NOW"
+  },
+  "status": "PAUSED"
+}