From f971bddc2035035809af089a6ac085f3daa0aa81 Mon Sep 17 00:00:00 2001 From: Illia Sapryga Date: Sun, 8 Nov 2026 16:11:15 -0600 Subject: [PATCH 1/6] Write gate: re-check blocked operations at apply, retire partial applies, shared draft helpers - confirm_and_apply refuses a plan whose operation was blocked after the draft (BLOCKED, dry run and apply alike), logs the refusal, and keeps the plan pending. The confirmation dialog is not shown for such a plan. - safety/outcomes.py: PartialApplyError. An applier raises it when part of a plan reached the account or a create's outcome is unknown; confirm_and_apply retires the plan and answers PARTIAL_APPLY or UNKNOWN_OUTCOME with what was created. - safety/guards.py: blocked_operation_error, store_draft and blocked_plan_refusal, used by Reddit and Tag Manager instead of their own copies. - Approval card: Microsoft Advertising and ChatGPT Ads labels, as in the confirmation dialog. --- .claude/rules/adloop.md | 2 + .cursor/rules/adloop.mdc | 2 + src/adloop/ads/write.py | 34 +++++++ src/adloop/gtm/write.py | 17 ++-- src/adloop/reddit/write.py | 20 ++--- src/adloop/rules/adloop.md | 2 + src/adloop/safety/approval.py | 6 ++ src/adloop/safety/approval_card.html | 6 +- src/adloop/safety/guards.py | 64 +++++++++++++- src/adloop/safety/outcomes.py | 23 +++++ src/adloop/safety/preview.py | 3 +- tests/test_confirmation_dialog.py | 7 ++ tests/test_platform_gate.py | 127 +++++++++++++++++++++++++++ 13 files changed, 283 insertions(+), 30 deletions(-) create mode 100644 src/adloop/safety/outcomes.py create mode 100644 tests/test_platform_gate.py diff --git a/.claude/rules/adloop.md b/.claude/rules/adloop.md index 0f641c23..5a696608 100644 --- a/.claude/rules/adloop.md +++ b/.claude/rules/adloop.md @@ -427,6 +427,8 @@ Same draft → preview → `confirm_and_apply` gate; the plan carries `platform: - `require_dry_run: true` in config overrides `dry_run=false` — the user must change the config to allow real mutations. - `two_phase_apply: true` in config (always on for AdLoop Cloud) refuses `dry_run=false` with status `DRY_RUN_REQUIRED` until that plan_id has completed one `dry_run=true` pass. Run the dry run, show the user, then apply — do not retry `dry_run=false` in a loop. - All operations (including dry runs) are logged to `~/.adloop/audit.log`. +- `blocked_operations` is checked again by `confirm_and_apply`: a plan whose operation was blocked after it was drafted is refused with status `BLOCKED`, dry run and apply alike, and no confirmation dialog is shown for it. +- **`PARTIAL_APPLY` and `UNKNOWN_OUTCOME`** (platforms without transactional writes): `PARTIAL_APPLY` means part of the change is in the account (`created` names it), from a multi-step apply whose later step failed or a batch the platform accepted only in part; `UNKNOWN_OUTCOME` means the platform never answered a create, so it may or may not exist. In both cases the plan is retired and cannot be applied again: read the account back, tell the user what exists, and draft only what is missing. ## Safety Rules (CRITICAL — always follow) diff --git a/.cursor/rules/adloop.mdc b/.cursor/rules/adloop.mdc index d727ff34..4a5afd9d 100644 --- a/.cursor/rules/adloop.mdc +++ b/.cursor/rules/adloop.mdc @@ -429,6 +429,8 @@ Same draft → preview → `confirm_and_apply` gate; the plan carries `platform: - `require_dry_run: true` in config overrides `dry_run=false` — the user must change the config to allow real mutations. - `two_phase_apply: true` in config (always on for AdLoop Cloud) refuses `dry_run=false` with status `DRY_RUN_REQUIRED` until that plan_id has completed one `dry_run=true` pass. Run the dry run, show the user, then apply — do not retry `dry_run=false` in a loop. - All operations (including dry runs) are logged to `~/.adloop/audit.log`. +- `blocked_operations` is checked again by `confirm_and_apply`: a plan whose operation was blocked after it was drafted is refused with status `BLOCKED`, dry run and apply alike, and no confirmation dialog is shown for it. +- **`PARTIAL_APPLY` and `UNKNOWN_OUTCOME`** (platforms without transactional writes): `PARTIAL_APPLY` means part of the change is in the account (`created` names it), from a multi-step apply whose later step failed or a batch the platform accepted only in part; `UNKNOWN_OUTCOME` means the platform never answered a create, so it may or may not exist. In both cases the plan is retired and cannot be applied again: read the account back, tell the user what exists, and draft only what is missing. ## Safety Rules (CRITICAL — always follow) diff --git a/src/adloop/ads/write.py b/src/adloop/ads/write.py index d3b94616..9bb0e575 100644 --- a/src/adloop/ads/write.py +++ b/src/adloop/ads/write.py @@ -2886,6 +2886,11 @@ def confirm_and_apply( "Plans expire when the MCP server restarts.", } + from adloop.safety.guards import blocked_plan_refusal + + if (refusal := blocked_plan_refusal(config, plan, dry_run=dry_run)) is not None: + return refusal + forced_by_config = bool(config.safety.require_dry_run) and not dry_run if config.safety.require_dry_run: dry_run = True @@ -3202,6 +3207,35 @@ def confirm_and_apply( and not e.sent_total and not e.unknown_status ) + from adloop.safety.outcomes import PartialApplyError + + if isinstance(e, PartialApplyError): + # Part of the change happened (or may have): replaying the plan + # would repeat it. Retire it and say what was done. + remove_plan(plan.plan_id) + log_mutation( + config.safety.log_file, + operation=plan.operation, + customer_id=plan.customer_id, + entity_type=plan.entity_type, + entity_id=plan.entity_id, + changes=plan.changes, + dry_run=False, + result="unknown_status" if e.unknown else "partial_apply", + error=error_message, + ) + return { + "status": "UNKNOWN_OUTCOME" if e.unknown else "PARTIAL_APPLY", + "plan_id": plan.plan_id, + "operation": plan.operation, + "error": error_message, + "created": e.created, + "message": ( + "Part of this change may already be in the account, so the plan was retired " + "and cannot be applied again. Read the account back, then draft only what is " + "still missing." + ), + } if not plan.operation.startswith("upload_") or nothing_written: store_plan(plan) diff --git a/src/adloop/gtm/write.py b/src/adloop/gtm/write.py index d0f6040b..f2b346e7 100644 --- a/src/adloop/gtm/write.py +++ b/src/adloop/gtm/write.py @@ -147,13 +147,9 @@ def _custom_html_refusal(what: str) -> dict: def _blocked(operation: str, config: AdLoopConfig) -> dict | None: - from adloop.safety.guards import SafetyViolation, check_blocked_operation + from adloop.safety.guards import blocked_operation_error - try: - check_blocked_operation(operation, config.safety) - except SafetyViolation as e: - return {"error": str(e)} - return None + return blocked_operation_error(operation, config.safety) def _client(config: AdLoopConfig): @@ -278,7 +274,8 @@ def _merge_parameters(existing: list[dict], updates: list[dict]) -> list[dict]: def _store(operation: str, entity_type: str, entity_id: str, changes: dict, *, warnings: list[str] | None = None, double_confirm: bool = False) -> dict: - from adloop.safety.preview import ChangePlan, store_plan + from adloop.safety.guards import store_draft + from adloop.safety.preview import ChangePlan plan = ChangePlan( operation=operation, @@ -289,11 +286,7 @@ def _store(operation: str, entity_type: str, entity_id: str, changes: dict, requires_double_confirm=double_confirm, platform=PLATFORM, ) - store_plan(plan) - preview = plan.to_preview() - if warnings: - preview["warnings"] = warnings - return preview + return store_draft(plan, warnings=warnings) def _workspace_digest(status: dict) -> str: diff --git a/src/adloop/reddit/write.py b/src/adloop/reddit/write.py index 777f0ba1..bca791bc 100644 --- a/src/adloop/reddit/write.py +++ b/src/adloop/reddit/write.py @@ -190,13 +190,9 @@ def _daily_equivalent( def _guard(operation: str, config: AdLoopConfig) -> dict | None: - from adloop.safety.guards import SafetyViolation, check_blocked_operation + from adloop.safety.guards import blocked_operation_error - try: - check_blocked_operation(operation, config.safety) - except SafetyViolation as e: - return {"error": str(e)} - return None + return blocked_operation_error(operation, config.safety) def _budget_cap(daily_equivalent: float | None, config: AdLoopConfig, currency: str) -> None: @@ -213,14 +209,10 @@ def _budget_cap(daily_equivalent: float | None, config: AdLoopConfig, currency: def _store(plan_kwargs: dict, *, warnings: list[str] | None = None) -> dict: - from adloop.safety.preview import ChangePlan, store_plan - - plan = ChangePlan(platform=PLATFORM, **plan_kwargs) - store_plan(plan) - preview = plan.to_preview() - if warnings: - preview["warnings"] = warnings - return preview + from adloop.safety.guards import store_draft + from adloop.safety.preview import ChangePlan + + return store_draft(ChangePlan(platform=PLATFORM, **plan_kwargs), warnings=warnings) def _fetch(config: AdLoopConfig, entity_type: str, entity_id: str) -> dict: diff --git a/src/adloop/rules/adloop.md b/src/adloop/rules/adloop.md index 0f641c23..5a696608 100644 --- a/src/adloop/rules/adloop.md +++ b/src/adloop/rules/adloop.md @@ -427,6 +427,8 @@ Same draft → preview → `confirm_and_apply` gate; the plan carries `platform: - `require_dry_run: true` in config overrides `dry_run=false` — the user must change the config to allow real mutations. - `two_phase_apply: true` in config (always on for AdLoop Cloud) refuses `dry_run=false` with status `DRY_RUN_REQUIRED` until that plan_id has completed one `dry_run=true` pass. Run the dry run, show the user, then apply — do not retry `dry_run=false` in a loop. - All operations (including dry runs) are logged to `~/.adloop/audit.log`. +- `blocked_operations` is checked again by `confirm_and_apply`: a plan whose operation was blocked after it was drafted is refused with status `BLOCKED`, dry run and apply alike, and no confirmation dialog is shown for it. +- **`PARTIAL_APPLY` and `UNKNOWN_OUTCOME`** (platforms without transactional writes): `PARTIAL_APPLY` means part of the change is in the account (`created` names it), from a multi-step apply whose later step failed or a batch the platform accepted only in part; `UNKNOWN_OUTCOME` means the platform never answered a create, so it may or may not exist. In both cases the plan is retired and cannot be applied again: read the account back, tell the user what exists, and draft only what is missing. ## Safety Rules (CRITICAL — always follow) diff --git a/src/adloop/safety/approval.py b/src/adloop/safety/approval.py index 79fad17f..fa81af5d 100644 --- a/src/adloop/safety/approval.py +++ b/src/adloop/safety/approval.py @@ -538,6 +538,12 @@ def _dialog_applies(plan_id: str) -> ChangePlan | None: if safety.two_phase_apply and plan.dry_run_result is None: # confirm_and_apply refuses with DRY_RUN_REQUIRED; don't ask first. return None + from adloop.safety.guards import blocked_operation_error + + if blocked_operation_error(plan.operation, safety) is not None: + # confirm_and_apply refuses with BLOCKED; asking first would have the + # user approve a change that cannot happen. + return None return plan diff --git a/src/adloop/safety/approval_card.html b/src/adloop/safety/approval_card.html index d0e4e980..0c7b7f97 100644 --- a/src/adloop/safety/approval_card.html +++ b/src/adloop/safety/approval_card.html @@ -126,7 +126,7 @@

gone: "Diese Änderung ist nicht mehr offen (angewendet, verworfen oder abgelaufen).", }, }; - const PLATFORMS = { google: "Google Ads", reddit: "Reddit Ads", ga4: "Google Analytics", gtm: "Tag Manager", google_ga4: "Google Ads · Analytics" }; + const PLATFORMS = { google: "Google Ads", reddit: "Reddit Ads", microsoft: "Microsoft Advertising", chatgpt: "ChatGPT Ads", ga4: "Google Analytics", gtm: "Tag Manager", google_ga4: "Google Ads · Analytics" }; const MAX_ROWS = 14; let lang = "en"; @@ -164,7 +164,7 @@

} function humanize(op) { - const s = String(op || "change").replace(/^(reddit|gtm|ga4)_/, "").replace(/_/g, " "); + const s = String(op || "change").replace(/^(reddit|microsoft|chatgpt|gtm|ga4)_/, "").replace(/_/g, " "); return s.charAt(0).toUpperCase() + s.slice(1); } @@ -172,6 +172,8 @@

const op = String(preview.operation || ""); if (op === "conversion_tracking_setup") return "google_ga4"; if (preview.platform === "reddit" || op.startsWith("reddit_")) return "reddit"; + if (preview.platform === "microsoft" || op.startsWith("microsoft_")) return "microsoft"; + if (preview.platform === "chatgpt" || op.startsWith("chatgpt_")) return "chatgpt"; if (op.startsWith("gtm_")) return "gtm"; if (preview.platform === "ga4" || op.startsWith("ga4_") || op.includes("key_event")) return "ga4"; return "google"; diff --git a/src/adloop/safety/guards.py b/src/adloop/safety/guards.py index 88b37646..841c8b12 100644 --- a/src/adloop/safety/guards.py +++ b/src/adloop/safety/guards.py @@ -5,7 +5,8 @@ from typing import TYPE_CHECKING if TYPE_CHECKING: - from adloop.config import SafetyConfig + from adloop.config import AdLoopConfig, SafetyConfig + from adloop.safety.preview import ChangePlan class SafetyViolation(Exception): @@ -54,3 +55,64 @@ def requires_double_confirmation(operation: str, **kwargs: object) -> bool: return True return False + + +# --------------------------------------------------------------------------- +# Shared by the draft tools and confirm_and_apply of every platform +# --------------------------------------------------------------------------- + + +def blocked_operation_error(operation: str, config: SafetyConfig) -> dict | None: + """A draft tool's refusal for a blocked operation, or None when it may proceed.""" + try: + check_blocked_operation(operation, config) + except SafetyViolation as e: + return {"error": str(e)} + return None + + +def store_draft(plan: ChangePlan, *, warnings: list[str] | None = None) -> dict: + """Store a drafted plan and return its preview, with the draft's warnings.""" + from adloop.safety.preview import store_plan + + store_plan(plan) + preview = plan.to_preview() + if warnings: + preview["warnings"] = warnings + return preview + + +def blocked_plan_refusal(config: AdLoopConfig, plan: ChangePlan, *, dry_run: bool) -> dict | None: + """confirm_and_apply's refusal for a plan whose operation is blocked now. + + The blocklist can grow after a plan was drafted, so it is checked again + before a dry run or an apply. The refusal is logged like any other + outcome; the plan stays pending, so it can still be discarded or applied + once the operation is unblocked. + """ + error = blocked_operation_error(plan.operation, config.safety) + if error is None: + return None + from adloop.safety.audit import log_mutation + + log_mutation( + config.safety.log_file, + operation=plan.operation, + customer_id=plan.customer_id, + entity_type=plan.entity_type, + entity_id=plan.entity_id, + changes=plan.changes, + dry_run=dry_run, + result="blocked", + error=error["error"], + ) + return { + "status": "BLOCKED", + "plan_id": plan.plan_id, + "operation": plan.operation, + "error": error["error"], + "message": ( + "Nothing was changed: this operation was added to safety.blocked_operations " + "after the plan was drafted, so it can neither be tested nor applied." + ), + } diff --git a/src/adloop/safety/outcomes.py b/src/adloop/safety/outcomes.py new file mode 100644 index 00000000..b99041dc --- /dev/null +++ b/src/adloop/safety/outcomes.py @@ -0,0 +1,23 @@ +"""Write outcomes that must not be replayed. + +An applier raises :class:`PartialApplyError` when part of a plan already +changed the account (a multi-step create whose later step failed, a batch +that created some items and rejected others) or when it cannot know whether +a create went through (the response was lost). ``confirm_and_apply`` then +retires the plan instead of keeping it pending: confirming it again would +repeat what already happened. The error says what was done, so the person +can check the account and draft only what is still missing. +""" + +from __future__ import annotations + +from typing import Any + + +class PartialApplyError(Exception): + """Part of the plan was applied, or its outcome is unknown; never replay it.""" + + def __init__(self, message: str, *, created: dict[str, Any] | None = None, unknown: bool = False): + super().__init__(message) + self.created = created or {} + self.unknown = unknown diff --git a/src/adloop/safety/preview.py b/src/adloop/safety/preview.py index 421bd754..a0e553ab 100644 --- a/src/adloop/safety/preview.py +++ b/src/adloop/safety/preview.py @@ -23,7 +23,8 @@ class ChangePlan: requires_double_confirm: bool = False dry_run_result: dict[str, Any] | None = None # Ad platform the plan targets: "" (Google, the default so stored plans - # from before the field existed still load) or "reddit". + # from before the field existed still load), "reddit", "gtm", "ga4", + # "microsoft" or "chatgpt". platform: str = "" # When a confirmation dialog for this plan was last sent and not yet # answered (ISO timestamp, "" when none is open). An app that receives diff --git a/tests/test_confirmation_dialog.py b/tests/test_confirmation_dialog.py index 7c042dfa..1bd01644 100644 --- a/tests/test_confirmation_dialog.py +++ b/tests/test_confirmation_dialog.py @@ -152,6 +152,13 @@ async def test_no_dialog_before_the_required_dry_run(fake_apply, tmp_path): assert asked == [] +async def test_no_dialog_for_an_operation_blocked_after_the_draft(fake_apply, tmp_path): + """confirm_and_apply refuses it with BLOCKED; the user is not asked to approve it first.""" + runtime.set_default_config(_config(tmp_path, blocked_operations=["pause_entity"])) + _status, asked = await _apply(_plan(), answer={"apply": True}) + assert asked == [] + + async def test_hosted_servers_skip_the_dialog_on_the_older_protocol(fake_apply): runtime.set_deployment_mode("server") status, asked = await _apply(_plan(), answer={"apply": False}, mode="legacy") diff --git a/tests/test_platform_gate.py b/tests/test_platform_gate.py new file mode 100644 index 00000000..87decf97 --- /dev/null +++ b/tests/test_platform_gate.py @@ -0,0 +1,127 @@ +"""What every platform shares in the write gate: blocked operations, partial applies, labels.""" + +import json +import re + +import pytest + +from adloop.ads import write as ads_write +from adloop.config import AdLoopConfig, SafetyConfig +from adloop.safety.approval import _PLATFORM_LABELS, card_html +from adloop.safety.guards import blocked_operation_error, blocked_plan_refusal, store_draft +from adloop.safety.outcomes import PartialApplyError +from adloop.safety.preview import ChangePlan, get_plan, remove_plan, store_plan + + +@pytest.fixture +def config(tmp_path): + return AdLoopConfig( + safety=SafetyConfig(log_file=str(tmp_path / "audit.log"), require_dry_run=False) + ) + + +def _audit(config) -> list[dict]: + with open(config.safety.log_file) as f: + return [json.loads(line) for line in f if line.strip()] + + +@pytest.fixture +def plan(): + plan = ChangePlan( + operation="example_pause_entity", entity_type="campaign", entity_id="123", + changes={"target_status": "PAUSED"}, + ) + store_plan(plan) + yield plan + remove_plan(plan.plan_id) + + +@pytest.fixture +def executed(monkeypatch): + calls = [] + + def execute(_config, plan): + calls.append(plan.plan_id) + return {"status": "APPLIED"} + + monkeypatch.setattr(ads_write, "_execute_plan", execute) + return calls + + +class TestBlockedOperations: + def test_draft_refusal_names_the_operation(self, config): + config.safety.blocked_operations = ["example_pause_entity"] + assert blocked_operation_error("example_pause_entity", config.safety) == { + "error": "Operation 'example_pause_entity' is blocked by configuration" + } + assert blocked_operation_error("example_enable_entity", config.safety) is None + + def test_store_draft_stores_the_plan_and_adds_the_warnings(self): + plan = ChangePlan(operation="example_pause_entity", platform="reddit") + preview = store_draft(plan, warnings=["Check the budget first."]) + assert get_plan(plan.plan_id) is plan + assert preview["warnings"] == ["Check the budget first."] + assert preview["platform"] == "reddit" + assert "warnings" not in store_draft(ChangePlan(operation="example_pause_entity")) + remove_plan(plan.plan_id) + + @pytest.mark.parametrize("dry_run", [True, False]) + def test_an_operation_blocked_after_the_draft_is_refused(self, config, plan, executed, dry_run): + config.safety.blocked_operations = ["example_pause_entity"] + + result = ads_write.confirm_and_apply(config, plan_id=plan.plan_id, dry_run=dry_run) + + assert result["status"] == "BLOCKED" + assert "blocked by configuration" in result["error"] + assert executed == [] + # The plan stays pending: it can still be discarded, or applied once unblocked. + assert get_plan(plan.plan_id) is not None + (entry,) = _audit(config) + assert entry["result"] == "blocked" and entry["dry_run"] is dry_run + assert entry["operation"] == "example_pause_entity" + + def test_the_refusal_is_none_while_the_operation_is_allowed(self, config, plan): + assert blocked_plan_refusal(config, plan, dry_run=True) is None + + +class TestPartialApply: + @pytest.mark.parametrize( + ("unknown", "status", "logged"), + [(False, "PARTIAL_APPLY", "partial_apply"), (True, "UNKNOWN_OUTCOME", "unknown_status")], + ) + def test_a_partial_apply_retires_the_plan(self, config, plan, monkeypatch, unknown, status, logged): + def execute(_config, _plan): + raise PartialApplyError( + "Created campaign 900; adding its locations failed.", + created={"campaign_id": "900"}, unknown=unknown, + ) + + monkeypatch.setattr(ads_write, "_execute_plan", execute) + + result = ads_write.confirm_and_apply(config, plan_id=plan.plan_id, dry_run=False) + + assert result["status"] == status + assert result["created"] == {"campaign_id": "900"} + assert "Created campaign 900" in result["error"] + assert get_plan(plan.plan_id) is None + assert _audit(config)[-1]["result"] == logged + + def test_any_other_failure_keeps_the_plan(self, config, plan, monkeypatch): + def execute(_config, _plan): + raise RuntimeError("connection reset") + + monkeypatch.setattr(ads_write, "_execute_plan", execute) + + result = ads_write.confirm_and_apply(config, plan_id=plan.plan_id, dry_run=False) + + assert result.get("status") not in ("PARTIAL_APPLY", "UNKNOWN_OUTCOME") + assert get_plan(plan.plan_id) is not None + + +def test_the_card_labels_every_platform_the_dialog_does(): + html = card_html() + table = re.search(r"const PLATFORMS = \{(.*?)\};", html).group(1) + card_keys = set(re.findall(r"(\w+):", table)) + assert set(_PLATFORM_LABELS) <= card_keys + prefix = re.search(r"replace\(/\^\(([a-z0-9|]+)\)_/", html).group(1).split("|") + assert {p for p in _PLATFORM_LABELS if p != "google"} <= set(prefix) From ccb447a856d115ddd40970d868c6c1dec3544295 Mon Sep 17 00:00:00 2001 From: Illia Sapryga Date: Sun, 8 Nov 2026 16:34:09 -0600 Subject: [PATCH 2/6] confirm_and_apply: the docstring names BLOCKED, PARTIAL_APPLY and UNKNOWN_OUTCOME --- src/adloop/server.py | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/src/adloop/server.py b/src/adloop/server.py index 116637b6..4a36b51b 100644 --- a/src/adloop/server.py +++ b/src/adloop/server.py @@ -5656,16 +5656,21 @@ def confirm_and_apply( request: then it carries out the rest and reports those operations again. Returns a status with the plan_id and operation: DRY_RUN_SUCCESS, - DRY_RUN_FAILED, DRY_RUN_REQUIRED, APPLIED, PARTIAL_UPLOAD or - APPLY_IN_PROGRESS. APPLIED results carry the created or changed resource + DRY_RUN_FAILED, DRY_RUN_REQUIRED, BLOCKED, APPLIED, PARTIAL_UPLOAD, + PARTIAL_APPLY, UNKNOWN_OUTCOME or APPLY_IN_PROGRESS. BLOCKED means the + operation was added to safety.blocked_operations after the draft: nothing + ran and the plan stays pending. APPLIED results carry the created or changed resource names under 'result'. PARTIAL_UPLOAD belongs to the upload tools: the batches it lists are already in the account, so the plan is retired. 'sent_total', 'accepted_total', 'rejected_total' and 'resume_from_line' say how far the upload got and at which CSV line a new draft continues; when a batch's fate is unknown, 'unknown_status', 'uncertain_lines' and 'row_errors' name the rows whose outcome has to be checked first. - APPLY_IN_PROGRESS means an earlier call claimed this plan first, so this - call executed nothing. + PARTIAL_APPLY and UNKNOWN_OUTCOME come from platforms without + transactional writes: part of the change is in the account ('created' + names it), or a create was never answered. The plan is retired; read the + account back and draft only what is missing. APPLY_IN_PROGRESS means an + earlier call claimed this plan first, so this call executed nothing. Approval cards: in AI apps that show AdLoop's approval card with the preview, dry_run=false is REFUSED with status APPROVE_ON_CARD, because From fb84cc7ed4a127c11bebb1c195dbedae70495a58 Mon Sep 17 00:00:00 2001 From: Illia Sapryga Date: Sun, 8 Nov 2026 16:16:05 -0600 Subject: [PATCH 3/6] Microsoft Advertising: reads, reports and campaign management Microsoft Advertising (Bing) through the REST API v13: Entra sign-in (authorization code + PKCE, device code as fallback), account, campaign, ad group, keyword, ad and extension reads, performance, search-term and location reports, the conversion setup audit, and campaign management behind the draft -> preview -> confirm_and_apply gate: budgets, status, campaigns and targeting, ad groups, keywords and bids, negatives and shared lists, RSAs, sitelinks, callouts, snippets, call and image extensions, and removal. Rebased onto the shared write-gate change instead of #127. --- .claude/rules/adloop.md | 48 +- .cursor/rules/adloop.mdc | 50 +- CLAUDE.md | 1 + README.md | 41 + config.yaml.example | 21 + src/adloop/__init__.py | 23 + src/adloop/ads/write.py | 25 +- src/adloop/auth.py | 23 + src/adloop/config.py | 32 + src/adloop/microsoft_ads/__init__.py | 14 + src/adloop/microsoft_ads/auth.py | 419 +++++ src/adloop/microsoft_ads/client.py | 347 ++++ src/adloop/microsoft_ads/manage.py | 2443 ++++++++++++++++++++++++++ src/adloop/microsoft_ads/read.py | 1263 +++++++++++++ src/adloop/microsoft_ads/write.py | 347 ++++ src/adloop/oauth_redirect.py | 135 ++ src/adloop/rules/adloop.md | 48 +- src/adloop/server.py | 1016 ++++++++++- src/adloop/uploads.py | 3 +- tests/test_health_check.py | 29 + tests/test_microsoft_ads.py | 1205 +++++++++++++ tests/test_microsoft_ads_manage.py | 1632 +++++++++++++++++ tests/test_oauth_redirect.py | 94 + tests/test_server.py | 1 + 24 files changed, 9244 insertions(+), 16 deletions(-) create mode 100644 src/adloop/microsoft_ads/__init__.py create mode 100644 src/adloop/microsoft_ads/auth.py create mode 100644 src/adloop/microsoft_ads/client.py create mode 100644 src/adloop/microsoft_ads/manage.py create mode 100644 src/adloop/microsoft_ads/read.py create mode 100644 src/adloop/microsoft_ads/write.py create mode 100644 src/adloop/oauth_redirect.py create mode 100644 tests/test_microsoft_ads.py create mode 100644 tests/test_microsoft_ads_manage.py create mode 100644 tests/test_oauth_redirect.py diff --git a/.claude/rules/adloop.md b/.claude/rules/adloop.md index 5a696608..3f0adc6b 100644 --- a/.claude/rules/adloop.md +++ b/.claude/rules/adloop.md @@ -12,7 +12,7 @@ You have access to AdLoop MCP tools that connect Google Ads, Reddit Ads and Goog | Tool | When to Use | Key Parameters | |------|-------------|----------------| -| `health_check` | First thing to run when tools are failing — tests OAuth token, GA4, Ads, and (when configured) Reddit Ads connectivity | (none) | +| `health_check` | First thing to run when tools are failing — tests OAuth token, GA4, Ads, and (when configured) Reddit Ads and Microsoft Advertising connectivity | (none) | **A tool you expect is missing?** Apps such as claude.ai, ChatGPT and Perplexity cache AdLoop's tool list from when the connection was made. `health_check` returns `adloop_version` and `tools_offered`, the tools this server offers to you. If the user asks for something a tool in `tools_offered` does and that tool isn't in your own tool list, don't improvise with other tools: tell the user their app shows an older list and to refresh the AdLoop connection (claude.ai: Settings → Connectors → AdLoop; ChatGPT: the AdLoop plugin's settings; Perplexity: remove and add the connector again; coding agents: reconnect the MCP server or start a new session). @@ -265,6 +265,50 @@ Reddit is a second ad platform with its own connection (own OAuth app, no develo 4. Cross-check `get_reddit_ads` for `REJECTED` ads (`rejection_reason`) and `PENDING_APPROVAL` — they explain missing spend 5. Present spend, clicks, CTR, CPC, conversions, CPA in account currency; compare against Google Ads only on CPA/ROAS, never on CTR (feed placements behave differently from search) +### Microsoft Advertising Tools + +Microsoft Advertising (Bing, Yahoo, AOL, DuckDuckGo search ads) through the REST API v13. Toolset `microsoft_ads`; needs `microsoft_ads.developer_token`, `microsoft_ads.client_id` (an Entra app with public client flows and the msads.manage permission) and a one-time `adloop microsoft-login` (browser sign-in on `http://localhost:8080/callback`; sign in with the user that has access to the ad accounts. Directories with security defaults block the device-code flow with sign-in error 530035, so `--device-code` is only a fallback). `customer_id` is the manager account, `ad_account_id` the default ad account; `list_microsoft_ads_accounts` shows both. + +| Tool | When to Use | Key Parameters | +|------|-------------|----------------| +| `list_microsoft_ads_accounts` | Discovery: the signed-in user, manager accounts, ad accounts (id, number, currency, time zone, status) | (none) | +| `get_microsoft_campaigns` | Budget (own or shared), bidding, languages, included/excluded locations and location intent | `include_targeting` | +| `get_microsoft_ad_groups` | Bid, network (search partners on/off), Audience Network exposure, dates, campaign status | `campaign_id` | +| `get_microsoft_keywords` | Match type, bid, status, editorial review, parent statuses | `campaign_id`, `ad_group_id` | +| `get_microsoft_ads` | Headlines (pins), descriptions, paths, final URLs, editorial review | `campaign_id`, `ad_group_id` | +| `get_microsoft_performance` | Spend, clicks, CTR, CPC, conversions, CPA, revenue, impression share and share lost to budget/rank | `level` (account/campaign/ad_group/keyword/ad), date range, `breakdown` (date/device), `campaign_id`, `compact` | +| `get_microsoft_search_terms` | What people searched, the keyword and match type it matched, waste candidates | date range, `campaign_id`, `min_clicks`, `compact` | +| `get_microsoft_location_performance` | Where clicks came from; people physically there vs searching about the place | date range, `group_by` (city/metro/state/postal_code/most_specific) | +| `get_microsoft_conversion_setup` | Audit: UET tag status, conversion goals (tracking status, excluded from bidding), campaign goals, clicks without conversions | date range, `min_clicks` | +| `update_microsoft_campaign_budget` | Draft a new daily budget (own budget only; capped by `max_daily_budget`) | `campaign_id`, `daily_budget` | +| `pause_microsoft_entity` / `enable_microsoft_entity` | Draft pausing or enabling a campaign, ad group, keyword or ad | `entity_type`, `entity_id`, `parent_id` (optional) | +| `search_microsoft_locations` | Location ids (country, state, metro, city, postal code) by name; Microsoft's file is cached | `query`, `location_type` | +| `update_microsoft_campaign` | Name, bid strategy (ManualCpc, EnhancedCpc, MaxClicks, MaxConversions + target CPA), tracking template, final URL suffix | `campaign_id` + fields | +| `update_microsoft_campaign_targeting` | Included / excluded locations (full lists), location intent, ad schedule (replaces; account time zone, or the searcher's when the campaign uses AdScheduleUseSearcherTimeZone: the preview's `hours_in` says which) | `campaign_id`, `location_ids`, `excluded_location_ids`, `location_intent`, `ad_schedule` | +| `draft_microsoft_campaign` | New Search campaign, paused, with budget, bidding, languages, locations, intent | `name`, `daily_budget`, `languages`, `location_ids` | +| `draft_microsoft_ad_group` / `update_microsoft_ad_group` | New ad group (with keywords) / name, default bid, network, Audience Network adjustment | `campaign_id` or `ad_group_id` + fields | +| `draft_microsoft_keywords` / `update_microsoft_keyword_bids` | Add keywords (duplicates skipped) / change keyword bids | `ad_group_id`, `keywords` or `bids` | +| `get_microsoft_negative_keywords` | Direct negatives and shared lists with items, attachments and `remove_id`s | `campaign_id` | +| `propose_microsoft_negative_keyword_list` / `add_to_microsoft_negative_keyword_list` | New shared list (attached) / append to a list | `list_name` or `list_id`, `keywords`, `campaign_ids` | +| `attach_microsoft_negative_keyword_list` / `detach_microsoft_negative_keyword_list` | Link or unlink a list and campaigns | `list_id`, `campaign_ids` | +| `add_microsoft_negative_keywords` | Negatives directly on a campaign or ad group | `campaign_id` or `ad_group_id`, `keywords` | +| `draft_microsoft_responsive_search_ad` / `update_microsoft_responsive_search_ad` | New RSA (paused) / replace headlines, descriptions, URL, paths | `ad_group_id` or `ad_id` + copy | +| `get_microsoft_ad_extensions` | Sitelinks, callouts, snippets, call and image extensions per ad group, campaign and account, with `remove_id`s (image rows add `alt_text`, `display_text`, `layouts`, `media_ids` and `images` with each picture's size and `url`, to look at a photo before unlinking it) | `campaign_id` | +| `draft_microsoft_sitelinks` / `draft_microsoft_callouts` / `draft_microsoft_structured_snippet` / `draft_microsoft_call_extension` | Create and link extensions to a campaign (or the account) | `campaign_id` or `scope="account"` + content | +| `draft_microsoft_image_extension` | Photos with the search ads: uploads up to 10 images to the media library, creates one image extension per image and links them | `campaign_id`, `ad_group_id` or `scope="account"`; `image_paths` / `image_urls` / `upload_ids`; `alt_text` (required, ≤35); optional `display_text` (≤35), `final_url` | +| `remove_microsoft_entity` | Delete (irreversible, double confirmation): campaign, ad group, ad, keyword, or by `remove_id` a negative, list item, criterion, extension link (account, campaign or ad group; unlinking keeps the extension) | `entity_type`, `entity_id` | + +- **Statuses at every level.** Keyword and ad rows carry the ad group and campaign status; reports carry `campaign_status`, `ad_group_status`, `keyword_status`. An account whose status is not Active serves nothing; `BudgetPaused` campaigns stopped on budget. +- **Location intent matters for local businesses.** `PeopleInOrSearchingForOrViewingPages` (Microsoft's default) also reaches people elsewhere searching about the area. `get_microsoft_location_performance` shows how much spend that "location of interest" traffic took. +- **Monthly spend:** Microsoft may spend up to 30.4 × the daily budget in a month; the budget preview says so. +- **Writes** go through draft → preview → `confirm_and_apply`. Microsoft has no validate-only mode: the dry run re-reads the target, refuses if the budget or status changed since the draft or the campaign moved to a shared budget, and re-checks the cap. The real apply runs the same checks again right before sending, so a change made in Microsoft Advertising in between is refused, not overwritten: draft again. Updates send only the changed field. +- **Management rules** mirror Google Ads: broad match is refused on ManualCpc / EnhancedCpc campaigns, moving to manual bidding is refused while active broad keywords exist, new campaigns need languages and locations (default PeopleIn), new RSAs and campaigns are paused, while new keywords and ad groups are created Active as in Google Ads (the preview's `status_on_create` says so, and keywords in a live ad group serve as soon as they are applied), keyword and ad group bid raises are capped by `max_bid_increase_pct` (including a keyword falling back to the ad group bid), a first ad schedule needs a double confirmation. Replacing a schedule window deletes the old window before adding the new one when they overlap; the preview warns when that leaves the campaign briefly unscheduled. Negative keywords go in shared lists by default; every negative draft names active keywords it would block. +- **Multi-step applies** (a campaign then its targeting, a list then its attachments, extensions then their links) end with `PARTIAL_APPLY` when a later step fails, or when Microsoft creates some items of a batch and refuses others: `created` lists the IDs that exist, and the plan is retired so nothing is created twice. Check the account, then draft only what is missing. +- **Image extensions** (`draft_microsoft_image_extension`): JPEG, PNG or non-animated GIF, at most 5 MB, **1.91:1** (e.g. 1200x628), at least 703x368, at most 2592 wide and 2048 high; the draft refuses anything else and says how to crop it. Ask the user for alt text that describes the photo. Microsoft's help allows 25 image extensions per account, campaign or ad group, its API reference says 6: the draft warns above 6 and refuses above 25. `display_text` adds the multi-image layout, which needs at least five images in four extensions. **Caution:** image extensions can take search ads beyond Bing results: Microsoft's audience ads guide says search ads are extended to native placements on the Microsoft Audience Network (Outlook, MSN) with their image extensions, so check the ad groups' Audience Network setting with `get_microsoft_ad_groups` when the client wants search only. Images without a public URL go through `upload_images` first. +- Reports are built asynchronously and take a few seconds; long date ranges at keyword or search-term level take longer. +- Search terms with clicks and no conversions are candidates, not verdicts: calls from Microsoft ads convert outside its view unless call tracking feeds back. +- **Conversions** come from Microsoft's `ConversionsQualified` columns (the old `Conversions` columns are deprecated and read 0 in keyword and search-term reports); conversion rate and CPA are computed from them. A UET tag is required only by URL, duration, pages-per-visit and event goals: offline-import goals need none, and an unverified tag that no active goal uses is a loose end (warn), not a broken setup. + ### When user asks about organic traffic, SEO, or paid/organic overlap 1. Call `list_gsc_sites` if no site is configured; confirm the property with the user @@ -293,7 +337,7 @@ For images that have no public URL: a file on the user's computer, or an image t - **With the card** (`upload: "card"` in the result): the user drops PNG, JPEG or GIF files (up to 5 MB) on the card; it then posts the upload ids into the chat. Wait for that message instead of asking for a URL. - **With an upload link** (`upload_url`): give the user the link (valid 30 minutes) to open in the browser, then call `list_uploads` once they say they are done. A coding agent that has the file on disk can upload it itself: `curl -T "logo.png" "/"`, one call per file. -- **Using an upload:** `draft_image_assets(upload_ids=["up_..."])` for Google Ads; `"upload:up_..."` as `image_url`, `thumbnail_url` or a carousel card's `image_url` in `draft_reddit_ad` (AdLoop Cloud only, because Reddit downloads the image from a short-lived public link). Videos cannot be uploaded. +- **Using an upload:** `draft_image_assets(upload_ids=["up_..."])` for Google Ads; `draft_microsoft_image_extension(upload_ids=["up_..."])` for Microsoft Advertising; `"upload:up_..."` as `image_url`, `thumbnail_url` or a carousel card's `image_url` in `draft_reddit_ad` (AdLoop Cloud only, because Reddit downloads the image from a short-lived public link). Videos cannot be uploaded. - Uploads expire after 24 hours. Self-hosted without a card, pass local files directly (`image_paths`). ### Offline Conversion Uploads diff --git a/.cursor/rules/adloop.mdc b/.cursor/rules/adloop.mdc index 4a5afd9d..5246170f 100644 --- a/.cursor/rules/adloop.mdc +++ b/.cursor/rules/adloop.mdc @@ -1,5 +1,5 @@ --- -description: AdLoop MCP orchestration — Google Ads + Reddit Ads + GA4 + codebase intelligence +description: AdLoop MCP orchestration — Google Ads + Reddit Ads + Microsoft Ads + GA4 + codebase intelligence globs: alwaysApply: true --- @@ -14,7 +14,7 @@ You have access to AdLoop MCP tools that connect Google Ads, Reddit Ads and Goog | Tool | When to Use | Key Parameters | |------|-------------|----------------| -| `health_check` | First thing to run when tools are failing — tests OAuth token, GA4, Ads, and (when configured) Reddit Ads connectivity | (none) | +| `health_check` | First thing to run when tools are failing — tests OAuth token, GA4, Ads, and (when configured) Reddit Ads and Microsoft Advertising connectivity | (none) | **A tool you expect is missing?** Apps such as claude.ai, ChatGPT and Perplexity cache AdLoop's tool list from when the connection was made. `health_check` returns `adloop_version` and `tools_offered`, the tools this server offers to you. If the user asks for something a tool in `tools_offered` does and that tool isn't in your own tool list, don't improvise with other tools: tell the user their app shows an older list and to refresh the AdLoop connection (claude.ai: Settings → Connectors → AdLoop; ChatGPT: the AdLoop plugin's settings; Perplexity: remove and add the connector again; coding agents: reconnect the MCP server or start a new session). @@ -267,6 +267,50 @@ Reddit is a second ad platform with its own connection (own OAuth app, no develo 4. Cross-check `get_reddit_ads` for `REJECTED` ads (`rejection_reason`) and `PENDING_APPROVAL` — they explain missing spend 5. Present spend, clicks, CTR, CPC, conversions, CPA in account currency; compare against Google Ads only on CPA/ROAS, never on CTR (feed placements behave differently from search) +### Microsoft Advertising Tools + +Microsoft Advertising (Bing, Yahoo, AOL, DuckDuckGo search ads) through the REST API v13. Toolset `microsoft_ads`; needs `microsoft_ads.developer_token`, `microsoft_ads.client_id` (an Entra app with public client flows and the msads.manage permission) and a one-time `adloop microsoft-login` (browser sign-in on `http://localhost:8080/callback`; sign in with the user that has access to the ad accounts. Directories with security defaults block the device-code flow with sign-in error 530035, so `--device-code` is only a fallback). `customer_id` is the manager account, `ad_account_id` the default ad account; `list_microsoft_ads_accounts` shows both. + +| Tool | When to Use | Key Parameters | +|------|-------------|----------------| +| `list_microsoft_ads_accounts` | Discovery: the signed-in user, manager accounts, ad accounts (id, number, currency, time zone, status) | (none) | +| `get_microsoft_campaigns` | Budget (own or shared), bidding, languages, included/excluded locations and location intent | `include_targeting` | +| `get_microsoft_ad_groups` | Bid, network (search partners on/off), Audience Network exposure, dates, campaign status | `campaign_id` | +| `get_microsoft_keywords` | Match type, bid, status, editorial review, parent statuses | `campaign_id`, `ad_group_id` | +| `get_microsoft_ads` | Headlines (pins), descriptions, paths, final URLs, editorial review | `campaign_id`, `ad_group_id` | +| `get_microsoft_performance` | Spend, clicks, CTR, CPC, conversions, CPA, revenue, impression share and share lost to budget/rank | `level` (account/campaign/ad_group/keyword/ad), date range, `breakdown` (date/device), `campaign_id`, `compact` | +| `get_microsoft_search_terms` | What people searched, the keyword and match type it matched, waste candidates | date range, `campaign_id`, `min_clicks`, `compact` | +| `get_microsoft_location_performance` | Where clicks came from; people physically there vs searching about the place | date range, `group_by` (city/metro/state/postal_code/most_specific) | +| `get_microsoft_conversion_setup` | Audit: UET tag status, conversion goals (tracking status, excluded from bidding), campaign goals, clicks without conversions | date range, `min_clicks` | +| `update_microsoft_campaign_budget` | Draft a new daily budget (own budget only; capped by `max_daily_budget`) | `campaign_id`, `daily_budget` | +| `pause_microsoft_entity` / `enable_microsoft_entity` | Draft pausing or enabling a campaign, ad group, keyword or ad | `entity_type`, `entity_id`, `parent_id` (optional) | +| `search_microsoft_locations` | Location ids (country, state, metro, city, postal code) by name; Microsoft's file is cached | `query`, `location_type` | +| `update_microsoft_campaign` | Name, bid strategy (ManualCpc, EnhancedCpc, MaxClicks, MaxConversions + target CPA), tracking template, final URL suffix | `campaign_id` + fields | +| `update_microsoft_campaign_targeting` | Included / excluded locations (full lists), location intent, ad schedule (replaces; account time zone, or the searcher's when the campaign uses AdScheduleUseSearcherTimeZone: the preview's `hours_in` says which) | `campaign_id`, `location_ids`, `excluded_location_ids`, `location_intent`, `ad_schedule` | +| `draft_microsoft_campaign` | New Search campaign, paused, with budget, bidding, languages, locations, intent | `name`, `daily_budget`, `languages`, `location_ids` | +| `draft_microsoft_ad_group` / `update_microsoft_ad_group` | New ad group (with keywords) / name, default bid, network, Audience Network adjustment | `campaign_id` or `ad_group_id` + fields | +| `draft_microsoft_keywords` / `update_microsoft_keyword_bids` | Add keywords (duplicates skipped) / change keyword bids | `ad_group_id`, `keywords` or `bids` | +| `get_microsoft_negative_keywords` | Direct negatives and shared lists with items, attachments and `remove_id`s | `campaign_id` | +| `propose_microsoft_negative_keyword_list` / `add_to_microsoft_negative_keyword_list` | New shared list (attached) / append to a list | `list_name` or `list_id`, `keywords`, `campaign_ids` | +| `attach_microsoft_negative_keyword_list` / `detach_microsoft_negative_keyword_list` | Link or unlink a list and campaigns | `list_id`, `campaign_ids` | +| `add_microsoft_negative_keywords` | Negatives directly on a campaign or ad group | `campaign_id` or `ad_group_id`, `keywords` | +| `draft_microsoft_responsive_search_ad` / `update_microsoft_responsive_search_ad` | New RSA (paused) / replace headlines, descriptions, URL, paths | `ad_group_id` or `ad_id` + copy | +| `get_microsoft_ad_extensions` | Sitelinks, callouts, snippets, call and image extensions per ad group, campaign and account, with `remove_id`s (image rows add `alt_text`, `display_text`, `layouts`, `media_ids` and `images` with each picture's size and `url`, to look at a photo before unlinking it) | `campaign_id` | +| `draft_microsoft_sitelinks` / `draft_microsoft_callouts` / `draft_microsoft_structured_snippet` / `draft_microsoft_call_extension` | Create and link extensions to a campaign (or the account) | `campaign_id` or `scope="account"` + content | +| `draft_microsoft_image_extension` | Photos with the search ads: uploads up to 10 images to the media library, creates one image extension per image and links them | `campaign_id`, `ad_group_id` or `scope="account"`; `image_paths` / `image_urls` / `upload_ids`; `alt_text` (required, ≤35); optional `display_text` (≤35), `final_url` | +| `remove_microsoft_entity` | Delete (irreversible, double confirmation): campaign, ad group, ad, keyword, or by `remove_id` a negative, list item, criterion, extension link (account, campaign or ad group; unlinking keeps the extension) | `entity_type`, `entity_id` | + +- **Statuses at every level.** Keyword and ad rows carry the ad group and campaign status; reports carry `campaign_status`, `ad_group_status`, `keyword_status`. An account whose status is not Active serves nothing; `BudgetPaused` campaigns stopped on budget. +- **Location intent matters for local businesses.** `PeopleInOrSearchingForOrViewingPages` (Microsoft's default) also reaches people elsewhere searching about the area. `get_microsoft_location_performance` shows how much spend that "location of interest" traffic took. +- **Monthly spend:** Microsoft may spend up to 30.4 × the daily budget in a month; the budget preview says so. +- **Writes** go through draft → preview → `confirm_and_apply`. Microsoft has no validate-only mode: the dry run re-reads the target, refuses if the budget or status changed since the draft or the campaign moved to a shared budget, and re-checks the cap. The real apply runs the same checks again right before sending, so a change made in Microsoft Advertising in between is refused, not overwritten: draft again. Updates send only the changed field. +- **Management rules** mirror Google Ads: broad match is refused on ManualCpc / EnhancedCpc campaigns, moving to manual bidding is refused while active broad keywords exist, new campaigns need languages and locations (default PeopleIn), new RSAs and campaigns are paused, while new keywords and ad groups are created Active as in Google Ads (the preview's `status_on_create` says so, and keywords in a live ad group serve as soon as they are applied), keyword and ad group bid raises are capped by `max_bid_increase_pct` (including a keyword falling back to the ad group bid), a first ad schedule needs a double confirmation. Replacing a schedule window deletes the old window before adding the new one when they overlap; the preview warns when that leaves the campaign briefly unscheduled. Negative keywords go in shared lists by default; every negative draft names active keywords it would block. +- **Multi-step applies** (a campaign then its targeting, a list then its attachments, extensions then their links) end with `PARTIAL_APPLY` when a later step fails, or when Microsoft creates some items of a batch and refuses others: `created` lists the IDs that exist, and the plan is retired so nothing is created twice. Check the account, then draft only what is missing. +- **Image extensions** (`draft_microsoft_image_extension`): JPEG, PNG or non-animated GIF, at most 5 MB, **1.91:1** (e.g. 1200x628), at least 703x368, at most 2592 wide and 2048 high; the draft refuses anything else and says how to crop it. Ask the user for alt text that describes the photo. Microsoft's help allows 25 image extensions per account, campaign or ad group, its API reference says 6: the draft warns above 6 and refuses above 25. `display_text` adds the multi-image layout, which needs at least five images in four extensions. **Caution:** image extensions can take search ads beyond Bing results: Microsoft's audience ads guide says search ads are extended to native placements on the Microsoft Audience Network (Outlook, MSN) with their image extensions, so check the ad groups' Audience Network setting with `get_microsoft_ad_groups` when the client wants search only. Images without a public URL go through `upload_images` first. +- Reports are built asynchronously and take a few seconds; long date ranges at keyword or search-term level take longer. +- Search terms with clicks and no conversions are candidates, not verdicts: calls from Microsoft ads convert outside its view unless call tracking feeds back. +- **Conversions** come from Microsoft's `ConversionsQualified` columns (the old `Conversions` columns are deprecated and read 0 in keyword and search-term reports); conversion rate and CPA are computed from them. A UET tag is required only by URL, duration, pages-per-visit and event goals: offline-import goals need none, and an unverified tag that no active goal uses is a loose end (warn), not a broken setup. + ### When user asks about organic traffic, SEO, or paid/organic overlap 1. Call `list_gsc_sites` if no site is configured; confirm the property with the user @@ -295,7 +339,7 @@ For images that have no public URL: a file on the user's computer, or an image t - **With the card** (`upload: "card"` in the result): the user drops PNG, JPEG or GIF files (up to 5 MB) on the card; it then posts the upload ids into the chat. Wait for that message instead of asking for a URL. - **With an upload link** (`upload_url`): give the user the link (valid 30 minutes) to open in the browser, then call `list_uploads` once they say they are done. A coding agent that has the file on disk can upload it itself: `curl -T "logo.png" "/"`, one call per file. -- **Using an upload:** `draft_image_assets(upload_ids=["up_..."])` for Google Ads; `"upload:up_..."` as `image_url`, `thumbnail_url` or a carousel card's `image_url` in `draft_reddit_ad` (AdLoop Cloud only, because Reddit downloads the image from a short-lived public link). Videos cannot be uploaded. +- **Using an upload:** `draft_image_assets(upload_ids=["up_..."])` for Google Ads; `draft_microsoft_image_extension(upload_ids=["up_..."])` for Microsoft Advertising; `"upload:up_..."` as `image_url`, `thumbnail_url` or a carousel card's `image_url` in `draft_reddit_ad` (AdLoop Cloud only, because Reddit downloads the image from a short-lived public link). Videos cannot be uploaded. - Uploads expire after 24 hours. Self-hosted without a card, pass local files directly (`image_paths`). ### Offline Conversion Uploads diff --git a/CLAUDE.md b/CLAUDE.md index d06e2041..0ec93f58 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -26,6 +26,7 @@ src/adloop/ ├── ga4/ # GA4 Data + Admin API (reports, realtime, events) ├── ads/ # Google Ads API (read, write, GAQL, forecasting, PMax, recommendations) ├── reddit/ # Reddit Ads API v3 (own OAuth app, REST client, reads, PAUSED-creating writes) +├── microsoft_ads/ # Microsoft Advertising (REST v13, Entra sign-in, reads, reports, campaign management) └── safety/ # Guards, previews, audit logging ``` diff --git a/README.md b/README.md index e058391e..28e148b5 100644 --- a/README.md +++ b/README.md @@ -246,6 +246,32 @@ A second ad platform, same safety model. Reddit is a separate connection: its ow > **Setup for Reddit Ads tools** — In Reddit Ads Manager open **Business Manager → Developer Application → Create app** (business admins only; no approval wait). Register the redirect URL exactly as `http://localhost:8765/callback`, then run `adloop init` and complete the Reddit Ads step: it opens Reddit's consent page (scopes `adsread` + `adsedit`, permanent grant), stores the refresh token at `~/.adloop/reddit_token.json`, and lets you pick the default ad account. Reddit rate-limits per user (reporting: 60 requests/min) and requires a descriptive User-Agent, which AdLoop builds from your app id and Reddit username. Reddit has no validate-only mode, so `confirm_and_apply(dry_run=true)` re-reads the target and re-checks the safety caps instead. +### Microsoft Advertising Tools + +Microsoft Advertising (Bing, Yahoo, AOL and DuckDuckGo search ads) through the REST API v13, with the same safety model. `customer_id` is the manager account and `ad_account_id` the default ad account; every tool takes `ad_account_id` to pick another. + +| Tool | What It Does | +|------|-------------| +| `list_microsoft_ads_accounts` | The signed-in user, manager accounts and ad accounts (id, number, currency, time zone, status) | +| `get_microsoft_campaigns` / `get_microsoft_ad_groups` / `get_microsoft_keywords` / `get_microsoft_ads` | Structure with the status of every parent level, budgets (own or shared), bidding, languages, included and excluded locations and location intent, bids, networks, Audience Network exposure, match types, RSA copy with pins, editorial review | +| `get_microsoft_performance` | Spend, clicks, CTR, CPC, conversions, CPA, revenue, impression share and share lost to budget and rank per account/campaign/ad group/keyword/ad, optional date or device breakdown, compact mode with insights | +| `get_microsoft_search_terms` | What people searched, the keyword and match type it matched, and waste candidates | +| `get_microsoft_location_performance` | Where clicks came from, split into people physically in a place and people searching about it | +| `get_microsoft_conversion_setup` | Audit of UET tags, conversion goals (tracking status, excluded from bidding), campaign goals and clicks without conversions | +| `get_microsoft_negative_keywords` / `get_microsoft_ad_extensions` | Direct negatives, shared negative lists with their items and attachments, and sitelinks, callouts, snippets and call extensions per campaign and account, each with a `remove_id` | +| `search_microsoft_locations` | Location ids (country, state, metro, city, postal code) by name from Microsoft's location file, cached | +| `update_microsoft_campaign_budget` / `update_microsoft_campaign` / `update_microsoft_campaign_targeting` | Daily budget (capped by `max_daily_budget`), name, bid strategy, tracking template and final URL suffix, included and excluded locations, location intent, ad schedule | +| `pause_microsoft_entity` / `enable_microsoft_entity` / `remove_microsoft_entity` | Status changes through the preview gate; removal is irreversible and double-confirmed | +| `draft_microsoft_campaign` / `draft_microsoft_ad_group` / `update_microsoft_ad_group` | New Search campaigns (created **paused**, with languages and locations required) and ad groups with keywords; ad group name, default bid, network and Audience Network adjustment | +| `draft_microsoft_keywords` / `update_microsoft_keyword_bids` | Add keywords (duplicates skipped) and change keyword bids, capped by `max_bid_increase_pct` including bids inherited from the ad group | +| `add_microsoft_negative_keywords` / `propose_microsoft_negative_keyword_list` / `add_to_microsoft_negative_keyword_list` / `attach_microsoft_negative_keyword_list` / `detach_microsoft_negative_keyword_list` | Negatives on a campaign or ad group, or in shared lists; every draft names the active keywords a negative would block | +| `draft_microsoft_responsive_search_ad` / `update_microsoft_responsive_search_ad` | New RSAs (created **paused**) and copy, URL and path changes | +| `draft_microsoft_sitelinks` / `draft_microsoft_callouts` / `draft_microsoft_structured_snippet` / `draft_microsoft_call_extension` | Create extensions and link them to a campaign or the account | + +The same management rules as Google Ads apply: broad match is refused on manual bidding (at the draft and again at apply), moving to manual bidding is refused while active broad keywords exist, and a campaign's first ad schedule needs a double confirmation. + +> **Setup for Microsoft Advertising tools** — You need a developer token (Microsoft Advertising → **Settings → Developer settings**, or [developers.ads.microsoft.com](https://developers.ads.microsoft.com/Account)) and an app registration in Microsoft Entra ID: allow public client flows, add the delegated `msads.manage` permission of Microsoft Advertising, and add `http://localhost:8080/callback` as a mobile and desktop redirect URI. Put the token and the app's client id under `microsoft_ads` in `~/.adloop/config.yaml`, then run `adloop microsoft-login` and sign in with the user that has access to the ad accounts. It stores the refresh token at `~/.adloop/microsoft_token.json`. Directories with security defaults block the device-code flow (sign-in error 530035), so `adloop microsoft-login --device-code` is only a fallback. Microsoft has no validate-only mode, so `confirm_and_apply(dry_run=true)` re-reads the target, refuses one that changed since the draft and re-checks the caps; the real apply runs the same checks again first. + ### Image Uploads An image on your computer, or one you attached in the chat, has no public URL, and an AI app cannot hand the file to a tool. `upload_images` gives it a way in. @@ -542,6 +568,13 @@ All configuration lives in `~/.adloop/config.yaml`. See [`config.yaml.example`]( | `reddit` | `ad_account_id` | *(empty)* | Default Reddit ad account for every Reddit tool (picked by `adloop init`) | | `reddit` | `username` | *(empty)* | Your Reddit username, used only in the User-Agent Reddit requires | | `reddit` | `token_path` | `~/.adloop/reddit_token.json` | Where the Reddit refresh token is stored | +| `microsoft_ads` | `developer_token` | *(empty)* | Microsoft Advertising developer token | +| `microsoft_ads` | `client_id` | *(empty)* | Client id of your Entra app registration (public client, `msads.manage` permission) | +| `microsoft_ads` | `client_secret` | *(empty)* | Only for a confidential (web) app; public clients leave it empty | +| `microsoft_ads` | `tenant` | `common` | Entra tenant for sign-in | +| `microsoft_ads` | `customer_id` | *(empty)* | Manager account id (the CustomerId header) | +| `microsoft_ads` | `ad_account_id` | *(empty)* | Default ad account for every Microsoft tool | +| `microsoft_ads` | `token_path` | `~/.adloop/microsoft_token.json` | Where `adloop microsoft-login` stores the refresh token | | `safety` | `max_daily_budget` | `50.00` | Maximum allowed daily budget per campaign | | `safety` | `require_dry_run` | `true` | Force all writes to dry-run mode | | `safety` | `two_phase_apply` | `false` | Refuse real applies until the plan had a dry-run pass | @@ -565,6 +598,7 @@ Most MCP clients (claude.ai, ChatGPT, Cursor, …) load **every tool schema into | `web` | PageSpeed / Core Web Vitals | | `merchant` | Merchant Center feed health | | `reddit` | Reddit Ads reads, writes, and planning | +| `microsoft_ads` | Microsoft Advertising reads and campaign management | Google Ads can be narrowed further. Use one of these instead of `ads`: @@ -608,6 +642,13 @@ src/adloop/ │ ├── client.py # Reddit Ads API v3 REST client — bearer refresh, per-user rate limits, pagination │ ├── read.py # Accounts, campaigns, ad groups, ads, performance reports, pixels, targeting lookups │ └── write.py # Draft/preflight/apply for status, budget, bid, targeting, and PAUSED creation +├── microsoft_ads/ +│ ├── auth.py # Entra sign-in (browser auth code + PKCE, device-code fallback), refresh tokens +│ ├── client.py # REST v13 client — Campaign Management, Customer Management, Reporting services +│ ├── read.py # Accounts, campaigns, ad groups, keywords, ads, reports, search terms, conversion audit +│ ├── manage.py # Drafts, preflight and apply for campaigns, targeting, keywords, negatives, ads, extensions +│ └── write.py # Budget and status drafts; routes every microsoft_ plan to its preflight and apply +├── oauth_redirect.py # One-shot localhost listener for sign-in redirects └── safety/ ├── guards.py # Budget caps, bid limits, blocked operations, Broad Match safety ├── preview.py # Change plans and previews diff --git a/config.yaml.example b/config.yaml.example index fc7ec79b..c95d1097 100644 --- a/config.yaml.example +++ b/config.yaml.example @@ -96,6 +96,27 @@ reddit: user_agent: "" token_path: "~/.adloop/reddit_token.json" +microsoft_ads: + # Microsoft Advertising / Bing (optional, REST API v13). Needs: + # 1. A developer token: Microsoft Advertising -> Settings -> Developer + # settings, or https://developers.ads.microsoft.com/Account. + # 2. An Entra app registered with "Allow public client flows" on and the + # Microsoft Advertising API permission msads.manage. Its application id: + # 3. `adloop microsoft-login` once: the browser opens, sign in with the + # account that has access to the ad accounts; the refresh token lands in + # token_path. The app needs http://localhost:8080/callback as a + # mobile/desktop redirect URI. (--device-code is a fallback; directories + # with security defaults block it with error 530035.) + developer_token: "" + client_id: "" + client_secret: "" # only for confidential (web) apps + tenant: "common" + # Manager account (CustomerId) and default ad account (CustomerAccountId); + # list_microsoft_ads_accounts shows both. + customer_id: "" + ad_account_id: "" + token_path: "~/.adloop/microsoft_token.json" + safety: # Maximum daily budget allowed per campaign (in your account's currency). # AdLoop will reject any campaign creation or budget change above this. diff --git a/src/adloop/__init__.py b/src/adloop/__init__.py index 3ba6773a..8212dc75 100644 --- a/src/adloop/__init__.py +++ b/src/adloop/__init__.py @@ -37,6 +37,9 @@ def main() -> None: adloop install-rules Install Claude orchestration rules globally. adloop update-rules Refresh the installed rules block. adloop uninstall-rules Remove the installed rules block + commands. + adloop microsoft-login Sign in to Microsoft Advertising in the browser + (--user preselects the account; --device-code + for the code-on-another-device flow). adloop --version, -V Print version and exit. """ args = sys.argv[1:] @@ -65,6 +68,26 @@ def main() -> None: sys.exit(130) return + if args and args[0] == "microsoft-login": + from adloop.config import load_config + from adloop.microsoft_ads.auth import MicrosoftAdsAuthError, browser_login, device_code_login + + options = args[1:] + hint = next((options[k + 1] for k, a in enumerate(options[:-1]) if a == "--user"), "") + try: + if "--device-code" in options: + path = device_code_login(load_config()) + else: + path = browser_login(load_config(), login_hint=hint) + except MicrosoftAdsAuthError as exc: + print(f"\n {exc}\n") + sys.exit(1) + except KeyboardInterrupt: + print("\n\n Cancelled.\n") + sys.exit(130) + print(f"\n Signed in. Token saved to {path}. Restart the MCP server to use it.\n") + return + # Process-global side effects (signal handlers, heartbeat thread, and # the stdio cancellation-race monkeypatch) are deliberately installed # here — in the stdio entry point — rather than at adloop.server import diff --git a/src/adloop/ads/write.py b/src/adloop/ads/write.py index 9bb0e575..38379e35 100644 --- a/src/adloop/ads/write.py +++ b/src/adloop/ads/write.py @@ -2898,6 +2898,7 @@ def confirm_and_apply( from adloop.ga4.write import GA4_OPERATIONS is_reddit = plan.operation.startswith("reddit_") + is_microsoft = plan.operation.startswith("microsoft_") is_gtm = plan.operation.startswith("gtm_") is_ga4 = plan.operation in GA4_OPERATIONS # Google Ads calls without a validate_only field: the dry run re-reads the @@ -2909,6 +2910,7 @@ def confirm_and_apply( platform_label = ( "Google Ads and Google Analytics" if is_setup else "Reddit Ads" if is_reddit + else "Microsoft Advertising" if is_microsoft else "Google Tag Manager" if is_gtm else "Google Analytics" if is_ga4 else "Google Ads" @@ -2923,14 +2925,19 @@ def confirm_and_apply( # Either way a failed check leaves dry_run_result unset, so two-phase # apply keeps refusing the real write. try: - if is_reddit or is_gtm: - # Neither Reddit nor Tag Manager has a validate-only mode; the - # dry run re-reads the target and re-runs the safety checks - # against live values. + if is_reddit or is_gtm or is_microsoft: + # Reddit, Microsoft Advertising and Tag Manager have no + # validate-only mode for these calls; the dry run re-reads the + # target and re-runs the safety checks against live values. from adloop.gtm.write import preflight as gtm_preflight + from adloop.microsoft_ads.write import preflight as microsoft_preflight from adloop.reddit.write import preflight as reddit_preflight - preflight = reddit_preflight if is_reddit else gtm_preflight + preflight = ( + reddit_preflight if is_reddit + else microsoft_preflight if is_microsoft + else gtm_preflight + ) preflight_checks = preflight(config, plan) elif is_ga4: # The GA4 Admin API has no validate-only mode either; a @@ -2987,7 +2994,7 @@ def confirm_and_apply( "Analytics by re-reading the property)" if is_setup else f"re-checked the target against {platform_label}" - if is_reddit or is_gtm or is_ga4 or is_ads_reread + if is_reddit or is_microsoft or is_gtm or is_ga4 or is_ads_reread else "sent the change to Google Ads in validate-only mode" ) return { @@ -4558,6 +4565,12 @@ def _execute_plan( return apply_plan(config, plan) + # Microsoft Advertising plans likewise have their own executor. + if plan.operation.startswith("microsoft_"): + from adloop.microsoft_ads.write import apply_plan as apply_microsoft_plan + + return apply_microsoft_plan(config, plan) + # Tag Manager plans likewise never touch the Ads client. if plan.operation.startswith("gtm_"): from adloop.gtm.write import apply_plan as apply_gtm_plan diff --git a/src/adloop/auth.py b/src/adloop/auth.py index 19eda2c5..9c15c564 100644 --- a/src/adloop/auth.py +++ b/src/adloop/auth.py @@ -19,6 +19,7 @@ from google.auth.credentials import Credentials from adloop.config import AdLoopConfig + from adloop.microsoft_ads.auth import MicrosoftCredentials from adloop.reddit.auth import RedditCredentials # Request all scopes in a single OAuth flow so one token works for both @@ -90,6 +91,8 @@ def merchant_credentials(self, config: AdLoopConfig) -> Credentials: ... def reddit_credentials(self, config: AdLoopConfig) -> RedditCredentials: ... + def microsoft_ads_credentials(self, config: AdLoopConfig) -> MicrosoftCredentials: ... + class LocalFileCredentialsProvider: """OSS default: local credential files + interactive OAuth. @@ -141,6 +144,14 @@ def reddit_credentials(self, config: AdLoopConfig) -> RedditCredentials: return local_credentials(config) + def microsoft_ads_credentials(self, config: AdLoopConfig) -> MicrosoftCredentials: + # Microsoft identity platform: own Entra app, own token file + # (microsoft_ads.token_path), written by `adloop microsoft-login`. + self._guard_local_only() + from adloop.microsoft_ads.auth import local_credentials + + return local_credentials(config) + _active_provider: CredentialsProvider = LocalFileCredentialsProvider() @@ -289,6 +300,18 @@ def get_reddit_credentials(config: AdLoopConfig) -> RedditCredentials: return provider.reddit_credentials(config) +def get_microsoft_ads_credentials(config: AdLoopConfig) -> MicrosoftCredentials: + """Return refreshable bearer credentials for the Microsoft Advertising API.""" + provider = _active_provider + if not hasattr(provider, "microsoft_ads_credentials"): + raise RuntimeError( + "This deployment's credentials provider does not support " + "Microsoft Advertising. Microsoft Ads tools are only available where " + "the provider implements microsoft_ads_credentials()." + ) + return provider.microsoft_ads_credentials(config) + + def _requested_scopes(config: AdLoopConfig) -> list[str]: """Scopes for the shared local token: the base set, plus GTM write scopes only when the user opted in via ``gtm.write_enabled``.""" diff --git a/src/adloop/config.py b/src/adloop/config.py index 02433f7d..14d9b48f 100644 --- a/src/adloop/config.py +++ b/src/adloop/config.py @@ -77,6 +77,27 @@ class RedditConfig: token_path: str = "~/.adloop/reddit_token.json" +@dataclass +class MicrosoftAdsConfig: + """Microsoft Advertising (Bing Ads) REST API. + + Needs a developer token (Microsoft Ads → Settings → Developer settings, + or developers.ads.microsoft.com) and an Entra app registered as a public + client with the msads.manage permission (``client_id``). ``adloop + microsoft-login`` signs in once and stores the refresh token at + ``token_path``. ``customer_id`` is the manager account (CustomerId + header); ``ad_account_id`` the default ad account (CustomerAccountId). + """ + + developer_token: str = "" + client_id: str = "" + client_secret: str = "" # only for confidential (web) apps; public clients leave it empty + tenant: str = "common" + customer_id: str = "" + ad_account_id: str = "" + token_path: str = "~/.adloop/microsoft_token.json" + + @dataclass class SafetyConfig: max_daily_budget: float = 50.0 @@ -108,6 +129,7 @@ class AdLoopConfig: merchant: MerchantConfig = field(default_factory=MerchantConfig) pagespeed: PageSpeedConfig = field(default_factory=PageSpeedConfig) reddit: RedditConfig = field(default_factory=RedditConfig) + microsoft_ads: MicrosoftAdsConfig = field(default_factory=MicrosoftAdsConfig) safety: SafetyConfig = field(default_factory=SafetyConfig) # Absolute path the config was resolved from (even if it did not exist # on disk when loaded). Used by the runtime to tell callers exactly @@ -179,6 +201,7 @@ def load_config(config_path: str | None = None) -> AdLoopConfig: merchant_raw = raw.get("merchant", {}) or {} pagespeed_raw = raw.get("pagespeed", {}) reddit_raw = raw.get("reddit", {}) or {} + microsoft_raw = raw.get("microsoft_ads", {}) or {} safety_raw = raw.get("safety", {}) return AdLoopConfig( @@ -219,6 +242,15 @@ def load_config(config_path: str | None = None) -> AdLoopConfig: user_agent=_text(reddit_raw, "user_agent"), token_path=_text(reddit_raw, "token_path", "~/.adloop/reddit_token.json"), ), + microsoft_ads=MicrosoftAdsConfig( + developer_token=_text(microsoft_raw, "developer_token"), + client_id=_text(microsoft_raw, "client_id"), + client_secret=_text(microsoft_raw, "client_secret"), + tenant=_text(microsoft_raw, "tenant", "common"), + customer_id=_text(microsoft_raw, "customer_id"), + ad_account_id=_text(microsoft_raw, "ad_account_id"), + token_path=_text(microsoft_raw, "token_path", "~/.adloop/microsoft_token.json"), + ), safety=SafetyConfig( max_daily_budget=safety_raw.get("max_daily_budget", 50.0), max_bid_increase_pct=safety_raw.get("max_bid_increase_pct", 100), diff --git a/src/adloop/microsoft_ads/__init__.py b/src/adloop/microsoft_ads/__init__.py new file mode 100644 index 00000000..dbc42c05 --- /dev/null +++ b/src/adloop/microsoft_ads/__init__.py @@ -0,0 +1,14 @@ +"""Microsoft Advertising (Bing Ads) integration — REST API v13. + +AdLoop's fourth ad platform. Microsoft is retiring the SOAP API on +2027-01-31, so this package talks to the REST API directly over +``requests`` (no SDK): Campaign Management, Customer Management and +Reporting. It carries the same layers as the Reddit package: OAuth +(``auth``), the authenticated HTTP wrapper and report runner (``client``), +read tools (``read``) and draft/preflight/apply executors (``write``) that +plug into the shared ``confirm_and_apply`` gate. + +Every call needs three things: an OAuth access token for a user with access +to the account (Microsoft identity platform, scope msads.manage), a +developer token, and the CustomerId / CustomerAccountId headers. +""" diff --git a/src/adloop/microsoft_ads/auth.py b/src/adloop/microsoft_ads/auth.py new file mode 100644 index 00000000..c893f193 --- /dev/null +++ b/src/adloop/microsoft_ads/auth.py @@ -0,0 +1,419 @@ +"""Microsoft Advertising OAuth — refresh-token credentials and device-code sign-in. + +Microsoft Advertising authenticates through the Microsoft identity platform +with the ``https://ads.microsoft.com/msads.manage`` scope. ``offline_access`` +returns a refresh token, which lasts up to 90 days and is rotated on every +refresh, so the new one must be stored each time (the local token file +here; a hosted deployment overrides :meth:`MicrosoftCredentials.persist`). + +``adloop microsoft-login`` signs in once in the browser (authorization code +with PKCE; the redirect lands on ``http://localhost:8080/callback``, which +the Entra app must list as a mobile/desktop redirect URI) and stores the +refresh token in ``token_path``. Directories with security defaults block +the device-code flow (sign-in error 530035), so it is only the fallback: +``adloop microsoft-login --device-code``. The Entra app must allow public +client flows. +""" + +from __future__ import annotations + +import json +import os +import threading +import time +from pathlib import Path +from typing import TYPE_CHECKING, Any, Callable + +if TYPE_CHECKING: + from adloop.config import AdLoopConfig + +SCOPE = "https://ads.microsoft.com/msads.manage offline_access" +_AUTHORITY = "https://login.microsoftonline.com/{tenant}/oauth2/v2.0" +_EXPIRY_MARGIN_SECONDS = 120 +_TIMEOUT_SECONDS = 30 +BROWSER_REDIRECT_URI = "http://localhost:8080/callback" +_BROWSER_LOGIN_TIMEOUT_SECONDS = 300 + + +class MicrosoftAdsAuthError(Exception): + """No usable credentials, or the identity platform refused them. + + Deliberately not a ``RuntimeError`` (see the Reddit and ChatGPT errors): + ``_structured_error`` gives it an actionable hint. + """ + + def __init__(self, message: str, *, error_code: str = ""): + super().__init__(message) + self.error_code = error_code + + +class MicrosoftAdsApiError(Exception): + """The Microsoft Advertising API answered with a fault.""" + + def __init__( + self, + message: str, + *, + status: int = 0, + url: str = "", + codes: list[str] | None = None, + tracking_id: str = "", + retry_after: int | None = None, + ): + super().__init__(message) + self.status = status + self.url = url + self.codes = codes or [] + self.tracking_id = tracking_id + self.retry_after = retry_after + + +def _token_url(tenant: str) -> str: + return _AUTHORITY.format(tenant=tenant or "common") + "/token" + + +def _device_code_url(tenant: str) -> str: + return _AUTHORITY.format(tenant=tenant or "common") + "/devicecode" + + +def _post_form(url: str, data: dict) -> tuple[int, dict]: + import requests + + response = requests.post(url, data=data, timeout=_TIMEOUT_SECONDS) + try: + payload = response.json() if response.content else {} + except ValueError: + payload = {} + return response.status_code, payload if isinstance(payload, dict) else {} + + +def _token_error(payload: dict, status: int, secrets: list[str] | None = None) -> MicrosoftAdsAuthError: + code = str(payload.get("error") or f"http_{status}") + description = str(payload.get("error_description") or "").split("\r\n")[0].strip() + for secret in sorted((x for x in secrets or [] if x and len(x) >= 4), key=len, reverse=True): + description = description.replace(secret, "[redacted]") + if code == "invalid_grant": + message = ( + "Microsoft refused the refresh token (invalid_grant): it expired (90 days " + "unused), was revoked, or the password changed. Run `adloop microsoft-login` again." + ) + elif code in ("invalid_client", "unauthorized_client"): + message = ( + "Microsoft rejected the app (client id or secret). Check microsoft_ads.client_id; " + "a public client app needs 'Allow public client flows' enabled." + ) + else: + message = f"Microsoft token request failed ({code})" + if description: + message += f" — {description}" + return MicrosoftAdsAuthError(message, error_code=code) + + +class MicrosoftCredentials: + """Refreshable bearer credentials for one Microsoft Advertising user.""" + + def __init__( + self, + *, + client_id: str, + refresh_token: str, + tenant: str = "common", + client_secret: str = "", + access_token: str = "", + expires_at: float = 0.0, + ): + if not client_id: + raise MicrosoftAdsAuthError( + "microsoft_ads.client_id is not set: the Entra app (public client with the " + "msads.manage permission) that AdLoop signs in with.", + error_code="missing_client", + ) + if not refresh_token: + raise MicrosoftAdsAuthError( + "No Microsoft Advertising sign-in yet. Run `adloop microsoft-login` and sign " + "in with the account that has access to the ad accounts.", + error_code="missing_refresh_token", + ) + self.client_id = client_id + self.client_secret = client_secret + self.tenant = tenant or "common" + self.refresh_token = refresh_token + self.access_token = access_token + self.expires_at = expires_at + self._lock = threading.Lock() + + def token(self) -> str: + with self._lock: + if not self.access_token or time.time() >= self.expires_at - _EXPIRY_MARGIN_SECONDS: + self._refresh_locked() + return self.access_token + + def invalidate(self) -> None: + with self._lock: + self.access_token = "" + self.expires_at = 0.0 + + def _refresh_locked(self) -> None: + data = { + "client_id": self.client_id, + "grant_type": "refresh_token", + "refresh_token": self.refresh_token, + "scope": SCOPE, + } + if self.client_secret: + data["client_secret"] = self.client_secret + status, payload = _post_form(_token_url(self.tenant), data) + if status != 200 or not payload.get("access_token"): + raise _token_error(payload, status, [self.client_secret, self.refresh_token, self.access_token]) + self.access_token = str(payload["access_token"]) + self.expires_at = time.time() + float(payload.get("expires_in") or 3600) + if payload.get("refresh_token"): + self.refresh_token = str(payload["refresh_token"]) + self.persist(payload) + + def persist(self, payload: dict) -> None: + """Store a rotated refresh token. Subclasses decide where.""" + + +class FileMicrosoftCredentials(MicrosoftCredentials): + """Credentials backed by the local token file (self-hosted).""" + + def __init__(self, *, token_path: Path, **kwargs: Any): + super().__init__(**kwargs) + self.token_path = token_path + + def persist(self, payload: dict) -> None: + write_token_file( + self.token_path, + { + "refresh_token": self.refresh_token, + "access_token": self.access_token, + "expires_at": self.expires_at, + "scope": payload.get("scope") or SCOPE, + }, + ) + + +def write_token_file(path: Path, data: dict) -> None: + """Write the token file with owner-only permissions.""" + path.parent.mkdir(parents=True, exist_ok=True) + tmp = path.with_suffix(path.suffix + ".tmp") + fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600) + with os.fdopen(fd, "w") as handle: + json.dump(data, handle) + os.replace(tmp, path) + + +def _token_path(config: AdLoopConfig) -> Path: + from adloop.config import _resolve_path + + return _resolve_path(config.microsoft_ads.token_path or "~/.adloop/microsoft_token.json") + + +_cache: dict[str, FileMicrosoftCredentials] = {} +_cache_lock = threading.Lock() + + +def local_credentials(config: AdLoopConfig) -> MicrosoftCredentials: + """Credentials from the token file, shared per path within the process.""" + cfg = config.microsoft_ads + path = _token_path(config) + with _cache_lock: + cached = _cache.get(str(path)) + if cached is not None and cached.client_id == cfg.client_id: + return cached + data: dict = {} + if path.exists(): + try: + data = json.loads(path.read_text()) + except (OSError, ValueError) as exc: + raise MicrosoftAdsAuthError( + f"Cannot read the Microsoft token file {path}: {exc}. Run `adloop microsoft-login`.", + error_code="missing_refresh_token", + ) from exc + creds = FileMicrosoftCredentials( + token_path=path, + client_id=cfg.client_id, + client_secret=cfg.client_secret, + tenant=cfg.tenant, + refresh_token=str(data.get("refresh_token") or ""), + access_token=str(data.get("access_token") or ""), + expires_at=float(data.get("expires_at") or 0.0), + ) + _cache[str(path)] = creds + return creds + + +def reset_credentials_cache() -> None: + with _cache_lock: + _cache.clear() + + +def device_code_login( + config: AdLoopConfig, + *, + say: Callable[[str], None] = print, + sleep: Callable[[float], None] = time.sleep, +) -> Path: + """Sign in once with the device-code flow and store the refresh token.""" + cfg = config.microsoft_ads + if not cfg.client_id: + raise MicrosoftAdsAuthError( + "Set microsoft_ads.client_id in ~/.adloop/config.yaml first (the Entra app id).", + error_code="missing_client", + ) + status, start = _post_form( + _device_code_url(cfg.tenant), {"client_id": cfg.client_id, "scope": SCOPE} + ) + if status != 200 or not start.get("device_code"): + raise _token_error(start, status) + say( + str(start.get("message") or "") + or f"Open {start.get('verification_uri')} and enter the code {start.get('user_code')}." + ) + say("Sign in with the Microsoft account that has access to the ad accounts.") + + interval = float(start.get("interval") or 5) + deadline = time.time() + float(start.get("expires_in") or 900) + while time.time() < deadline: + sleep(interval) + data = { + "client_id": cfg.client_id, + "grant_type": "urn:ietf:params:oauth:grant-type:device_code", + "device_code": start["device_code"], + } + if cfg.client_secret: + data["client_secret"] = cfg.client_secret + status, payload = _post_form(_token_url(cfg.tenant), data) + if status == 200 and payload.get("refresh_token"): + path = _token_path(config) + write_token_file( + path, + { + "refresh_token": payload["refresh_token"], + "access_token": payload.get("access_token", ""), + "expires_at": time.time() + float(payload.get("expires_in") or 3600), + "scope": payload.get("scope") or SCOPE, + }, + ) + reset_credentials_cache() + return path + error = payload.get("error") + if error == "authorization_pending": + continue + if error == "slow_down": + interval += 5 + continue + raise _token_error(payload, status) + raise MicrosoftAdsAuthError("The sign-in code expired before it was used. Run the command again.", + error_code="expired_token") + + +def _pkce_pair() -> tuple[str, str]: + import base64 + import hashlib + import secrets + + verifier = secrets.token_urlsafe(64)[:96] + challenge = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).decode().rstrip("=") + return verifier, challenge + + +def authorize_url(config: AdLoopConfig, *, state: str, challenge: str, redirect_uri: str, login_hint: str = "") -> str: + from urllib.parse import urlencode + + params = { + "client_id": config.microsoft_ads.client_id, + "response_type": "code", + "redirect_uri": redirect_uri, + "response_mode": "query", + "scope": SCOPE, + "state": state, + "code_challenge": challenge, + "code_challenge_method": "S256", + "prompt": "select_account", + } + if login_hint: + params["login_hint"] = login_hint + return _AUTHORITY.format(tenant=config.microsoft_ads.tenant or "common") + "/authorize?" + urlencode(params) + + +def browser_login( + config: AdLoopConfig, + *, + login_hint: str = "", + redirect_uri: str = BROWSER_REDIRECT_URI, + say: Callable[[str], None] = print, + open_browser: Callable[[str], Any] | None = None, + listen: Callable[[str], dict] | None = None, +) -> Path: + """Sign in once in the browser (authorization code + PKCE) and store the refresh token.""" + import secrets + + cfg = config.microsoft_ads + if not cfg.client_id: + raise MicrosoftAdsAuthError( + "Set microsoft_ads.client_id in ~/.adloop/config.yaml first (the Entra app id).", + error_code="missing_client", + ) + if open_browser is None: + import webbrowser + + open_browser = webbrowser.open + if listen is None: + from adloop.oauth_redirect import RedirectTimeout, listen_once + + def listen(uri: str) -> dict: + try: + return listen_once(uri, _BROWSER_LOGIN_TIMEOUT_SECONDS, provider="Microsoft Advertising") + except RedirectTimeout: + raise MicrosoftAdsAuthError( + "No sign-in arrived within 5 minutes. Run the command again.", error_code="timeout", + ) from None + except OSError as exc: + raise MicrosoftAdsAuthError( + f"Cannot listen on {uri} ({exc}); close whatever uses that port, or run " + "`adloop microsoft-login --device-code`.", error_code="port_in_use", + ) from None + + state = secrets.token_urlsafe(16) + verifier, challenge = _pkce_pair() + url = authorize_url(config, state=state, challenge=challenge, redirect_uri=redirect_uri, login_hint=login_hint) + say("Opening Microsoft sign-in in your browser. Sign in with the user that has access to the") + say("Microsoft Advertising accounts. If the browser does not open, visit:") + say(f" {url}") + try: + open_browser(url) + except Exception: # noqa: BLE001 — the URL is printed + pass + query = listen(redirect_uri) + if query.get("error"): + description = str(query.get("error_description") or query["error"]).split("\r\n")[0] + raise MicrosoftAdsAuthError(f"Microsoft did not complete the sign-in: {description}", error_code=str(query["error"])) + if query.get("state") != state: + raise MicrosoftAdsAuthError("The sign-in response does not belong to this sign-in; run the command again.", + error_code="state_mismatch") + if not query.get("code"): + raise MicrosoftAdsAuthError("The sign-in response carried no authorization code.", error_code="no_code") + data = { + "client_id": cfg.client_id, + "grant_type": "authorization_code", + "code": query["code"], + "redirect_uri": redirect_uri, + "code_verifier": verifier, + "scope": SCOPE, + } + if cfg.client_secret: + data["client_secret"] = cfg.client_secret + status, payload = _post_form(_token_url(cfg.tenant), data) + if status != 200 or not payload.get("refresh_token"): + raise _token_error(payload, status, [cfg.client_secret, query["code"]]) + path = _token_path(config) + write_token_file(path, { + "refresh_token": payload["refresh_token"], + "access_token": payload.get("access_token", ""), + "expires_at": time.time() + float(payload.get("expires_in") or 3600), + "scope": payload.get("scope") or SCOPE, + }) + reset_credentials_cache() + return path diff --git a/src/adloop/microsoft_ads/client.py b/src/adloop/microsoft_ads/client.py new file mode 100644 index 00000000..132aacd1 --- /dev/null +++ b/src/adloop/microsoft_ads/client.py @@ -0,0 +1,347 @@ +"""Microsoft Advertising REST client: headers, faults, retries, reports. + +Every call goes through :func:`ms_request`: + +- **Headers**: ``Authorization: Bearer``, ``DeveloperToken``, ``CustomerId`` + (manager account) and ``CustomerAccountId`` (ad account). Bodies and + responses are JSON with PascalCase names; flag enums such as + ``CampaignType`` travel as comma-separated strings ("Search, Shopping"). +- **Faults**: Microsoft returns ``AdApiFaultDetail`` (``Errors``) or + ``ApiFaultDetail`` (``OperationErrors`` / ``BatchErrors``) bodies; the + codes and messages are folded into one :class:`MicrosoftAdsApiError`. + An expired token (codes 105/109 or HTTP 401) is refreshed once. +- **Throttling**: HTTP 429 or code 117 (CallRateExceeded) waits briefly and + retries; a long wait surfaces as an error instead of blocking the call. + +Reports are asynchronous: :func:`run_report` submits, polls, downloads the +zipped CSV and returns its rows as dicts keyed by column name. +""" + +from __future__ import annotations + +import csv +import io +import time +import zipfile +from typing import TYPE_CHECKING, Any + +from adloop.microsoft_ads.auth import MicrosoftAdsApiError, MicrosoftAdsAuthError + +if TYPE_CHECKING: + from adloop.config import AdLoopConfig + +HOSTS = { + "campaign": "https://campaign.api.bingads.microsoft.com/CampaignManagement/v13", + "customer": "https://clientcenter.api.bingads.microsoft.com/CustomerManagement/v13", + "reporting": "https://reporting.api.bingads.microsoft.com/Reporting/v13", +} +DEVELOPER_SETTINGS_URL = "https://developers.ads.microsoft.com/Account" + +_TIMEOUT_SECONDS = 60 +_MAX_THROTTLE_RETRIES = 3 +_MAX_THROTTLE_WAIT_SECONDS = 10 +# Codes that mean the access token is not (or no longer) accepted. +_AUTH_CODES = {"105", "109", "AuthenticationTokenExpired", "InvalidCredentials"} +_THROTTLE_CODES = {"117", "CallRateExceeded"} +_MAX_MESSAGE = 500 + + +def _credentials(config: AdLoopConfig): + from adloop.auth import get_microsoft_ads_credentials + + return get_microsoft_ads_credentials(config) + + +def _user_agent() -> str: + from importlib.metadata import PackageNotFoundError, version + + try: + return f"adloop/{version('adloop')}" + except PackageNotFoundError: + return "adloop/dev" + + +def fault_details(payload: Any) -> tuple[list[str], str, str]: + """(codes, message, tracking id) from any of Microsoft's fault shapes.""" + if not isinstance(payload, dict): + return [], "", "" + entries: list[dict] = [] + for key in ("Errors", "OperationErrors", "BatchErrors", "PartialErrors"): + value = payload.get(key) + if isinstance(value, list): + entries.extend(e for e in value if isinstance(e, dict)) + # Some faults nest the detail one level down. + for key in ("Detail", "detail", "FaultDetail"): + inner = payload.get(key) + if isinstance(inner, dict): + codes, message, tracking = fault_details(inner) + if codes or message: + return codes, message, tracking or str(payload.get("TrackingId") or "") + codes = [str(e.get("ErrorCode") or e.get("Code") or "") for e in entries] + parts = [] + for e in entries[:5]: + text = str(e.get("Message") or e.get("Details") or e.get("ErrorCode") or "") + label = e.get("ErrorCode") or e.get("Code") + field = e.get("FieldPath") + parts.append(f"{label}: {text}" + (f" ({field})" if field else "") if label else text) + message = "; ".join(p for p in parts if p) or str( + payload.get("Message") or payload.get("message") or payload.get("error") or "" + ) + numeric = [str(e.get("Code")) for e in entries if e.get("Code") is not None] + return [c for c in codes + numeric if c], message[:_MAX_MESSAGE], str(payload.get("TrackingId") or "") + + +def _retry_after(headers: Any) -> int | None: + raw = headers.get("Retry-After") if headers is not None else None + try: + return max(int(float(raw)), 0) if raw is not None else None + except (TypeError, ValueError): + return None + + +def ms_request( + config: AdLoopConfig, + service: str, + path: str, + body: dict | None = None, + *, + method: str = "POST", + account_id: str = "", + customer_id: str = "", + mutation: bool = False, +) -> dict: + """One authenticated call to a Microsoft Advertising REST service. + + ``mutation`` marks a call that changes the account (an apply); it only + changes what a lost connection is said to mean. + """ + import requests + + cfg = config.microsoft_ads + if not cfg.developer_token: + raise MicrosoftAdsAuthError( + "microsoft_ads.developer_token is not set. Request one in Microsoft Advertising " + f"(Settings → Developer settings, or {DEVELOPER_SETTINGS_URL}) and add it to the config.", + error_code="missing_developer_token", + ) + creds = _credentials(config) + url = f"{HOSTS[service]}/{path.lstrip('/')}" + headers = { + "DeveloperToken": cfg.developer_token, + "Content-Type": "application/json", + "Accept": "application/json", + "User-Agent": _user_agent(), + } + customer = customer_id or cfg.customer_id + if customer: + headers["CustomerId"] = str(customer) + if account_id: + headers["CustomerAccountId"] = str(account_id) + + refreshed = False + throttled = 0 + while True: + headers["Authorization"] = f"Bearer {creds.token()}" + try: + response = requests.request( + method.upper(), url, json=body if body is not None else {}, headers=headers, + timeout=_TIMEOUT_SECONDS, + ) + except requests.RequestException as exc: + # A read can simply be repeated; a change may already have been + # made before the connection broke. + after = "the change may or may not have been made" if mutation else "try again" + raise MicrosoftAdsApiError( + f"Could not reach Microsoft Advertising for {path} ({type(exc).__name__}); {after}." + ) from None + status = response.status_code + try: + payload = response.json() if response.content else {} + except ValueError: + payload = {} + # A fault may echo the request; keep every credential out of errors, + # tool results and the audit log. A successful batch can carry item + # errors too (PartialErrors, NestedPartialErrors), so those are + # scrubbed as well; the rest of a successful answer is left alone. + secrets = [headers["Authorization"][len("Bearer "):], cfg.developer_token, cfg.client_secret, + getattr(creds, "refresh_token", ""), getattr(creds, "access_token", "")] + if 200 <= status < 300: + if not isinstance(payload, dict): + return {"data": payload} + for key in _ERROR_KEYS: + if payload.get(key): + payload[key] = _scrub(payload[key], secrets) + return payload + + payload = _scrub(payload, secrets) + codes, message, tracking = fault_details(payload) + if (status == 401 or set(codes) & _AUTH_CODES) and not refreshed: + refreshed = True + creds.invalidate() + continue + if status == 429 or set(codes) & _THROTTLE_CODES: + throttled += 1 + wait = _retry_after(response.headers) + wait = 5 if wait is None else wait + if throttled <= _MAX_THROTTLE_RETRIES and wait <= _MAX_THROTTLE_WAIT_SECONDS: + time.sleep(max(wait, 1)) + continue + raise MicrosoftAdsApiError( + "Microsoft Advertising rate limit reached" + + (f"; retry after {wait}s" if wait else "") + + ". Wait before calling again; do not retry in a loop.", + status=429, url=url, codes=codes, tracking_id=tracking, retry_after=wait, + ) + if status == 401 or set(codes) & _AUTH_CODES: + raise MicrosoftAdsAuthError( + "Microsoft Advertising rejected the sign-in even after a refresh" + + (f": {message}" if message else "") + + ". Run `adloop microsoft-login` again.", + error_code="invalid_credentials", + ) + raise MicrosoftAdsApiError( + f"Microsoft Advertising API returned {status} for {path}" + + (f": {message}" if message else "") + + (f" (tracking id {tracking})" if tracking else ""), + status=status, url=url, codes=codes, tracking_id=tracking, + ) + + +# Response fields that carry errors, also inside a successful (2xx) answer. +_ERROR_KEYS = ("PartialErrors", "NestedPartialErrors", "Errors", "OperationErrors", "BatchErrors") + + +def _scrub(value: Any, secrets: list[str]) -> Any: + """A parsed response with every secret (8+ characters) redacted from its strings.""" + if isinstance(value, str): + for secret in secrets: + if secret and len(secret) >= 8: + value = value.replace(secret, "[redacted]") + return value + if isinstance(value, dict): + return {k: _scrub(v, secrets) for k, v in value.items()} + if isinstance(value, list): + return [_scrub(v, secrets) for v in value] + return value + + +def campaign_request(config: AdLoopConfig, path: str, body: dict, *, account_id: str, + customer_id: str = "", method: str = "POST", mutation: bool = False) -> dict: + return ms_request(config, "campaign", path, body, method=method, account_id=account_id, + customer_id=customer_id, mutation=mutation) + + +def customer_request(config: AdLoopConfig, path: str, body: dict, *, account_id: str = "") -> dict: + return ms_request(config, "customer", path, body, account_id=account_id) + + +# --------------------------------------------------------------------------- +# Reports +# --------------------------------------------------------------------------- + + +def _date(value) -> dict: + return {"Day": value.day, "Month": value.month, "Year": value.year} + + +def report_time(start, end, time_zone: str = "") -> dict: + time_block: dict[str, Any] = { + "CustomDateRangeStart": _date(start), + "CustomDateRangeEnd": _date(end), + } + if time_zone: + time_block["ReportTimeZone"] = time_zone + return time_block + + +def parse_csv(data: bytes) -> list[dict]: + """Rows of a report CSV (optionally zipped), keyed by column name.""" + if data[:2] == b"PK": + with zipfile.ZipFile(io.BytesIO(data)) as archive: + names = [n for n in archive.namelist() if not n.endswith("/")] + if not names: + return [] + data = archive.read(names[0]) + text = data.decode("utf-8-sig", errors="replace") + reader = csv.DictReader(io.StringIO(text)) + rows = [] + for row in reader: + if not row or all(v in (None, "") for v in row.values()): + continue + # A report footer ("©2026 Microsoft Corporation") would land in the first column. + first = next(iter(row.values()), "") or "" + if first.startswith("©") or "Microsoft Corporation" in first: + continue + rows.append({k: (v if v is not None else "") for k, v in row.items() if k is not None}) + return rows + + +def download_file(url: str, *, what: str = "file") -> bytes: + """Fetch a signed download URL; an error never repeats the URL.""" + import requests + + try: + response = requests.get(url, timeout=_TIMEOUT_SECONDS) + except requests.RequestException as exc: + raise MicrosoftAdsApiError(f"Downloading the {what} failed ({type(exc).__name__}); run the tool again.") from None + if response.status_code >= 400: + raise MicrosoftAdsApiError( + f"Downloading the {what} failed with HTTP {response.status_code}; the link may have " + "expired, run the tool again.", + status=response.status_code, + ) + return response.content + + +def run_report( + config: AdLoopConfig, + report_request: dict, + *, + account_id: str, + customer_id: str = "", + timeout_seconds: float = 90, + sleep=time.sleep, +) -> list[dict]: + """Submit a report, poll until it is ready, download and parse it.""" + request = { + "Format": "Csv", + "ExcludeReportHeader": True, + "ExcludeReportFooter": True, + "ExcludeColumnHeaders": False, + "ReturnOnlyCompleteData": False, + **report_request, + } + submitted = ms_request( + config, "reporting", "GenerateReport/Submit", {"ReportRequest": request}, + account_id=account_id, customer_id=customer_id, + ) + request_id = submitted.get("ReportRequestId") + if not request_id: + raise MicrosoftAdsApiError("Microsoft accepted the report request but returned no id.") + + waited = 0.0 + delay = 1.0 + while True: + polled = ms_request( + config, "reporting", "GenerateReport/Poll", {"ReportRequestId": request_id}, + account_id=account_id, customer_id=customer_id, + ) + status_block = polled.get("ReportRequestStatus") or {} + status = str(status_block.get("Status") or "") + if status == "Success": + url = status_block.get("ReportDownloadUrl") + if not url: + return [] # Microsoft returns no file when the report has no rows. + return parse_csv(download_file(url, what=f"{report_request.get('Type') or 'report'} file")) + if status == "Error": + raise MicrosoftAdsApiError( + f"Microsoft could not build the {report_request.get('Type')} report." + ) + if waited >= timeout_seconds: + raise MicrosoftAdsApiError( + f"The {report_request.get('Type')} report was not ready after " + f"{int(timeout_seconds)}s; try a shorter date range." + ) + sleep(delay) + waited += delay + delay = min(delay * 2, 8.0) diff --git a/src/adloop/microsoft_ads/manage.py b/src/adloop/microsoft_ads/manage.py new file mode 100644 index 00000000..0bbebef2 --- /dev/null +++ b/src/adloop/microsoft_ads/manage.py @@ -0,0 +1,2443 @@ +"""Microsoft Advertising management: campaigns, targeting, ad groups, keywords, +negatives, responsive search ads, ad extensions (image extensions included) +and removals. + +Every function here drafts a :class:`ChangePlan` (platform ``microsoft``, +operation ``microsoft_*``) and returns its preview; nothing changes until +``confirm_and_apply``. :mod:`adloop.microsoft_ads.write` routes these +operations to :func:`preflight` and :func:`apply_plan` below. + +Microsoft's Campaign Management API has no validate-only mode, so: + +- **Updates** store a snapshot of every field they change; the dry run and + the apply re-read the entity and refuse when one of those fields was + edited in Microsoft Advertising since the preview. +- **Creates** re-check their parents, the safety caps and (for named + objects) that the name is still free, so a retried apply after a partial + failure refuses instead of creating a second copy. +- **Multi-step applies** (a campaign and then its targeting, a list and then + its attachments) report exactly what was created when a later step fails. + +REST conventions (learn.microsoft.com/advertising/campaign-management-service): +add is POST, update PUT, delete DELETE on the collection path; polymorphic +objects carry a ``Type`` discriminator; on update an omitted field stays as +it is and a list that is sent replaces the old one. +""" + +from __future__ import annotations + +import base64 +import copy +import hashlib +import json +from typing import TYPE_CHECKING, Any + +from adloop.microsoft_ads.auth import MicrosoftAdsApiError +from adloop.microsoft_ads.client import campaign_request, fault_details +from adloop.microsoft_ads.read import ( + _ad_groups, + _ads, + _bidding, + _campaigns, + _conversion_goals, + _criterions, + _customer, + _keywords, + _money, + account_meta, +) +from adloop.microsoft_ads.write import _guard, _store, _validation_error, find_entity + +if TYPE_CHECKING: + from adloop.config import AdLoopConfig + from adloop.safety.preview import ChangePlan + +STRATEGIES = ("ManualCpc", "EnhancedCpc", "MaxClicks", "MaxConversions") +_SMART = {"MaxClicks", "MaxConversions"} +_MANUAL = {"ManualCpc", "EnhancedCpc"} +MATCH_TYPES = ("Exact", "Phrase", "Broad") +NEGATIVE_MATCH_TYPES = ("Exact", "Phrase") +NETWORKS = ("OwnedAndOperatedOnly", "OwnedAndOperatedAndSyndicatedSearch") +INTENTS = ("PeopleIn", "PeopleInOrSearchingForOrViewingPages") +DAYS = ("Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday") +_MINUTES = {0: "Zero", 15: "Fifteen", 30: "Thirty", 45: "FortyFive"} +_PINS = { + "headline_1": "Headline1", "headline_2": "Headline2", "headline_3": "Headline3", + "headline1": "Headline1", "headline2": "Headline2", "headline3": "Headline3", + "description_1": "Description1", "description_2": "Description2", + "description1": "Description1", "description2": "Description2", +} +_EXTENSION_TYPES = ("SitelinkAdExtension, CalloutAdExtension, StructuredSnippetAdExtension, CallAdExtension, " + "ImageAdExtension") +_LIST_TYPE = "NegativeKeywordList" +_MAX_LISTS_PER_CAMPAIGN = 20 +_CHUNK = 100 + + +# --------------------------------------------------------------------------- +# Shared helpers +# --------------------------------------------------------------------------- + + +def _ctx(config: AdLoopConfig, ad_account_id: str) -> tuple[dict, str, str]: + meta = account_meta(config, ad_account_id) + return meta, meta["ad_account_id"], _customer(config, meta) + + +def _clean(values: Any) -> list[str]: + if values is None: + return [] + if isinstance(values, (str, int)): + values = [values] + return [str(v).strip() for v in values if str(v).strip()] + + +def _same(a: Any, b: Any) -> bool: + return json.dumps(a, sort_keys=True, default=str) == json.dumps(b, sort_keys=True, default=str) + + +def _check_url(url: str, errors: list[str], warnings: list[str], field: str = "final_url") -> None: + if not url.startswith(("http://", "https://")): + errors.append(f"{field} must start with http:// or https://") + return + from adloop.ads.write import _validate_urls + + bad, inconclusive = _validate_urls([url]) + if bad.get(url): + errors.append(f"{field} '{url}' is not reachable: {bad[url]}") + warnings.extend(inconclusive.values()) + + +_ID_FIELDS = ("CampaignIds", "AdGroupIds", "KeywordIds", "AdIds", "CampaignCriterionIds", "ListItemIds", "MediaIds") + + +def _created_ids(payload: dict) -> list[str]: + """IDs a create reported as done (failed items come back as null).""" + ids: list[str] = [] + for field in _ID_FIELDS: + ids += [str(i) for i in payload.get(field) or [] if i is not None] + ids += [str((i or {}).get("Id")) for i in payload.get("AdExtensionIdentities") or [] if i and i.get("Id")] + if payload.get("SharedEntityId"): + ids.append(str(payload["SharedEntityId"])) + for group in payload.get("NegativeKeywordIds") or []: + ids += [str(i) for i in (group or {}).get("Ids") or [] if i is not None] + return ids + + +def _partial_errors(payload: dict) -> list[dict]: + entries = [e for e in payload.get("PartialErrors") or [] if e] + for nested in payload.get("NestedPartialErrors") or []: + if not isinstance(nested, dict): + continue + entries.extend(e for e in nested.get("BatchErrors") or [] if e) + if nested.get("ErrorCode") or nested.get("Message"): + entries.append(nested) + return entries + + +def _raise_partial(payload: dict, what: str) -> None: + entries = _partial_errors(payload) + if not entries: + return + _codes, message, _tracking = fault_details({"PartialErrors": entries}) + created = _created_ids(payload) + if created: + # Some items were created and some refused: replaying the plan would + # create the successful ones again. + from adloop.safety.outcomes import PartialApplyError + + raise PartialApplyError( + f"Microsoft created part of the {what} (ids {created}) and refused the rest: {message or entries}", + created={what: created}, + ) + raise MicrosoftAdsApiError(f"Microsoft refused the {what}: {message or entries}") + + +def _call(config: AdLoopConfig, changes: dict, method: str, path: str, body: dict, what: str) -> dict: + try: + payload = campaign_request( + config, path, body, account_id=changes["ad_account_id"], customer_id=changes.get("customer_id", ""), + method=method, mutation=True, + ) + except MicrosoftAdsApiError as exc: + if method == "POST" and (exc.status == 0 or exc.status >= 500): + # The request may have reached Microsoft and created something: + # these creates have no idempotency, so replaying the plan could + # create it twice. Retire the plan and say so. + from adloop.safety.outcomes import PartialApplyError + + raise PartialApplyError( + f"Microsoft did not confirm the {what} ({exc}); it may or may not have been created. " + "Check the account before drafting it again.", + unknown=True, + ) from None + raise + _raise_partial(payload, what) + return payload + + +class _Progress: + """What a multi-step apply already changed, for an honest error. + + Once one step has changed the account, a failure in a later step retires + the plan (PartialApplyError) instead of leaving it to be replayed. + """ + + def __init__(self) -> None: + self.done: list[str] = [] + # IDs of what the earlier steps created, by kind, for the error. + self.created: dict[str, list[str]] = {} + + def step(self, what: str, fn): + from adloop.safety.outcomes import PartialApplyError + + try: + return fn() + except PartialApplyError as exc: + if self.done: + raise PartialApplyError( + f"{exc} (after: {'; '.join(self.done)})", + created={**self.created, **exc.created, "done": list(self.done)}, unknown=exc.unknown, + ) from None + raise + except Exception as exc: + if self.done: + raise PartialApplyError( + f"{what} failed after these steps succeeded: {'; '.join(self.done)}. " + f"Microsoft said: {exc}. Check the account before drafting again.", + created={**self.created, "done": list(self.done)}, + ) from None + raise + + +def _base_changes(account: str, customer: str, **extra: Any) -> dict: + return {"ad_account_id": account, "customer_id": customer, **extra} + + +def _plan(operation: str, entity_type: str, entity_id: str, account: str, changes: dict, + *, warnings: list[str] | None = None, double: bool = False) -> dict: + return _store( + {"operation": operation, "entity_type": entity_type, "entity_id": str(entity_id or ""), + "customer_id": account, "requires_double_confirm": double, "changes": changes}, + warnings=warnings, + ) + + +def _chunks(items: list, size: int = _CHUNK) -> list[list]: + return [items[i : i + size] for i in range(0, len(items), size)] + + +# --------------------------------------------------------------------------- +# Bidding +# --------------------------------------------------------------------------- + + +def bidding_scheme(strategy: str, *, target_cpa: float | None, max_cpc: float | None) -> dict: + scheme: dict[str, Any] = {"Type": strategy} + if strategy == "MaxConversions" and target_cpa is not None: + scheme["TargetCpa"] = round(float(target_cpa), 2) + if strategy in _SMART and max_cpc is not None: + scheme["MaxCpc"] = {"Amount": round(float(max_cpc), 2)} + return scheme + + +def _strategy_name(scheme: dict | None) -> str: + return str((scheme or {}).get("Type") or "").replace("BiddingScheme", "") + + +def _counted_goals(config: AdLoopConfig, account: str, customer: str) -> int: + try: + goals = _conversion_goals(config, account, customer) + except MicrosoftAdsApiError: + return -1 + return sum(1 for g in goals if g.get("Status") == "Active" and not g.get("ExcludeFromBidding")) + + +# --------------------------------------------------------------------------- +# Campaign settings +# --------------------------------------------------------------------------- + + +def update_microsoft_campaign( + config: AdLoopConfig, + *, + ad_account_id: str = "", + campaign_id: str = "", + name: str = "", + bidding_strategy: str = "", + target_cpa: float | None = None, + max_cpc: float | None = None, + tracking_url_template: str | None = None, + final_url_suffix: str | None = None, +) -> dict: + """Draft campaign setting changes: name, bid strategy, tracking template, final URL suffix.""" + operation = "microsoft_update_campaign" + blocked = _guard(operation, config) + if blocked: + return blocked + errors: list[str] = [] + campaign_id = str(campaign_id or "").strip() + if not campaign_id: + errors.append("campaign_id is required") + if name and len(name.strip()) > 128: + errors.append("name is at most 128 characters.") + strategy = (bidding_strategy or "").strip() + if strategy == "TargetCpa": + strategy = "MaxConversions" + if strategy and strategy not in STRATEGIES: + errors.append(f"bidding_strategy must be one of {list(STRATEGIES)}.") + if target_cpa is not None and (strategy or "") not in ("", "MaxConversions"): + errors.append("target_cpa goes with MaxConversions.") + template = None if tracking_url_template is None else tracking_url_template.strip() + if template and not template.startswith(("http://", "https://", "{lpurl}", "{unescapedlpurl}")): + errors.append("tracking_url_template must start with {lpurl}, {unescapedlpurl}, http:// or https://.") + if errors: + return _validation_error(errors) + meta, account, customer = _ctx(config, ad_account_id) + found = find_entity(config, account, customer, "campaign", campaign_id) + if not found: + return {"error": f"Microsoft campaign '{campaign_id}' was not found in account {account}."} + campaign = found["entity"] + update: dict[str, Any] = {"Id": campaign_id} + shown: dict[str, Any] = {} + warnings: list[str] = [] + touched: list[str] = [] + if name and name.strip() != campaign.get("Name"): + others = {str(c.get("Name")).lower() for c in _campaigns(config, account, customer) if str(c.get("Id")) != campaign_id} + if name.strip().lower() in others: + return _validation_error([f"Another campaign is already named '{name.strip()}'."]) + update["Name"] = name.strip() + shown["name"] = {"from": campaign.get("Name"), "to": name.strip()} + touched.append("Name") + current_scheme = campaign.get("BiddingScheme") or {} + if strategy or target_cpa is not None or max_cpc is not None: + chosen = strategy or _strategy_name(current_scheme) + if chosen not in STRATEGIES: + return _validation_error([f"The campaign uses {chosen or 'an unknown strategy'}; pass bidding_strategy explicitly."]) + has_cap = (current_scheme.get("MaxCpc") or {}).get("Amount") is not None + if max_cpc is not None and not has_cap and chosen in _SMART: + return _validation_error([ + "Microsoft no longer lets a campaign add a maximum CPC to automated bidding; it can " + "only change or remove an existing one." + ]) + keep_cap = (current_scheme.get("MaxCpc") or {}).get("Amount") if chosen == _strategy_name(current_scheme) else None + scheme = bidding_scheme( + chosen, + target_cpa=target_cpa if target_cpa is not None else (current_scheme.get("TargetCpa") if chosen == "MaxConversions" and _strategy_name(current_scheme) == "MaxConversions" else None), + max_cpc=max_cpc if max_cpc is not None else keep_cap, + ) + update["BiddingScheme"] = scheme + touched.append("BiddingScheme") + shown["bidding"] = {"from": _bidding(current_scheme), "to": _bidding(scheme), "currency": meta["currency"]} + if chosen != _strategy_name(current_scheme): + warnings.append("Changing the bid strategy restarts Microsoft's learning period; expect a week or two of unsettled results.") + if chosen == "MaxConversions" and _counted_goals(config, account, customer) == 0: + warnings.append("No active conversion goal counts toward Conversions: MaxConversions has nothing to optimize for.") + old_cap = (current_scheme.get("MaxCpc") or {}).get("Amount") + new_cap = (scheme.get("MaxCpc") or {}).get("Amount") + try: + _check_bid(old_cap, new_cap, config) + except Exception as e: # SafetyViolation + return {"error": f"Maximum CPC: {e}"} + if chosen in _MANUAL: + broad = _active_broad_keywords(config, account, customer, campaign_id) + if broad: + return _validation_error([ + f"The campaign has {len(broad)} active broad-match keyword(s); manual bidding with broad " + "match wastes spend. Change them to phrase or exact first." + ]) + for field, value, api_name in (("tracking_url_template", template, "TrackingUrlTemplate"), + ("final_url_suffix", None if final_url_suffix is None else final_url_suffix.strip(), "FinalUrlSuffix")): + if value is None or value == (campaign.get(api_name) or ""): + continue + update[api_name] = value + touched.append(api_name) + shown[field] = {"from": campaign.get(api_name) or None, "to": value or None} + if value == "": + warnings.append(f"{field} is removed.") + if len(update) == 1: + return {"error": "Nothing to change: pass at least one setting that differs from the campaign."} + return _plan( + operation, "campaign", campaign_id, account, + _base_changes(account, customer, entity_name=campaign.get("Name"), campaign_status=campaign.get("Status"), + changes=shown, update=update, + before={k: copy.deepcopy(campaign.get(k)) for k in sorted(set(touched))}), + warnings=warnings, + ) + + +# --------------------------------------------------------------------------- +# Targeting: locations, location intent, ad schedule +# --------------------------------------------------------------------------- + + +def _current_targeting(config: AdLoopConfig, account: str, customer: str, campaign_id: str) -> dict: + locations = _criterions(config, account, customer, campaign_id, "Location") + included = {} + excluded = {} + for c in locations: + crit = c.get("Criterion") or {} + entry = {"criterion_id": str(c.get("Id")), "name": crit.get("DisplayName") or str(crit.get("LocationId"))} + target = excluded if c.get("Type") == "NegativeCampaignCriterion" else included + target[str(crit.get("LocationId"))] = entry + intent = _criterions(config, account, customer, campaign_id, "LocationIntent") + schedule = _criterions(config, account, customer, campaign_id, "DayTime") + return { + "included": included, + "excluded": excluded, + "intent": {"criterion_id": str(intent[0].get("Id")), + "option": (intent[0].get("Criterion") or {}).get("IntentOption")} if intent else None, + "schedule": [ + {"criterion_id": str(c.get("Id")), **{k: (c.get("Criterion") or {}).get(k) + for k in ("Day", "FromHour", "FromMinute", "ToHour", "ToMinute")}} + for c in schedule + ], + } + + +def _schedule_blocks(schedule: list, errors: list[str]) -> list[dict]: + blocks = [] + for i, raw in enumerate(schedule or []): + if not isinstance(raw, dict): + errors.append(f"ad_schedule[{i}] must be an object with day_of_week, start_hour, end_hour.") + continue + day = str(raw.get("day_of_week") or raw.get("day") or "").strip().title() + try: + start_h, end_h = int(raw.get("start_hour")), int(raw.get("end_hour")) + start_m, end_m = int(raw.get("start_minute") or 0), int(raw.get("end_minute") or 0) + except (TypeError, ValueError): + errors.append(f"ad_schedule[{i}] hours and minutes must be whole numbers.") + continue + if day not in DAYS: + errors.append(f"ad_schedule[{i}].day_of_week must be one of {list(DAYS)}, got '{raw.get('day_of_week') or raw.get('day')}'.") + if not (0 <= start_h <= 23 and 0 <= end_h <= 24) or (end_h == 24 and end_m): + errors.append(f"ad_schedule[{i}] hours are 0–23 to start and 0–24 to end (24 only with minute 0).") + if start_m not in _MINUTES or end_m not in _MINUTES: + errors.append(f"ad_schedule[{i}] minutes are 0, 15, 30 or 45.") + if (end_h, end_m) <= (start_h, start_m): + errors.append(f"ad_schedule[{i}] must end after it starts.") + blocks.append({"Day": day, "FromHour": start_h, "FromMinute": _MINUTES.get(start_m, "Zero"), + "ToHour": end_h, "ToMinute": _MINUTES.get(end_m, "Zero")}) + by_day: dict[str, list] = {} + for b in blocks: + by_day.setdefault(b["Day"], []).append(b) + for day, items in by_day.items(): + minutes = sorted((b["FromHour"] * 60 + list(_MINUTES.values()).index(b["FromMinute"]) * 15, + b["ToHour"] * 60 + list(_MINUTES.values()).index(b["ToMinute"]) * 15) for b in items) + if any(a[1] > b[0] for a, b in zip(minutes, minutes[1:])): + errors.append(f"ad_schedule windows on {day} overlap.") + if len(items) > 6: + errors.append(f"At most 6 ad_schedule windows on {day}.") + return blocks + + +# Microsoft: "the maximum number of day and time criteria per day that you +# can set is seven" (per campaign or ad group). +_MAX_WINDOWS_PER_DAY = 7 + + +def _block_span(b: dict) -> tuple[str, int, int]: + """(day, start minute, end minute) of a DayTime window.""" + rev = {v: k for k, v in _MINUTES.items()} + return (str(b.get("Day")), int(b.get("FromHour") or 0) * 60 + rev.get(b.get("FromMinute"), 0), + int(b.get("ToHour") or 0) * 60 + rev.get(b.get("ToMinute"), 0)) + + +def _schedule_steps(current: list[dict], blocks: list[dict], campaign_id: str) -> dict: + """Order a schedule replacement the way Microsoft allows it. + + A DayTime window cannot be edited, only deleted and added, and windows + in a campaign must not overlap. Unchanged windows stay; new windows that + overlap none of today's go in first; then the old ones are deleted; then + the remaining new ones are added. ``gap`` is True when, between the last + two steps, the campaign has no window at all (it then serves at all hours). + """ + old = {_block_span(c): c for c in current} + new = {_block_span(b): b for b in blocks} + keep = set(old) & set(new) + remove = [old[s]["criterion_id"] for s in old if s not in keep] + to_add = [new[s] for s in new if s not in keep] + + def overlaps(span: tuple[str, int, int]) -> bool: + return any(o[0] == span[0] and span[1] < o[2] and o[1] < span[2] for o in old if o not in keep) + + def item(b: dict) -> dict: + return {"Type": "BiddableCampaignCriterion", "CampaignId": campaign_id, + "Criterion": {"Type": "DayTimeCriterion", **b}, + "CriterionBid": {"Type": "BidMultiplier", "Multiplier": 0}} + + # Before the deletes, a day still holds all of today's windows, and + # Microsoft allows at most seven per day: add early only what fits. + room = {} + for span in old: + room[span[0]] = room.get(span[0], _MAX_WINDOWS_PER_DAY) - 1 + first, after = [], [] + for b in to_add: + span = _block_span(b) + if not overlaps(span) and room.get(span[0], _MAX_WINDOWS_PER_DAY) > 0: + room[span[0]] = room.get(span[0], _MAX_WINDOWS_PER_DAY) - 1 + first.append(item(b)) + else: + after.append(item(b)) + return {"schedule_add_first": first, "schedule_delete": remove, "schedule_add_after": after, + "schedule_kept": [_block_label(old[s]) for s in old if s in keep], + "gap": bool(after) and not keep and not first} + + +def _block_label(b: dict) -> str: + rev = {v: k for k, v in _MINUTES.items()} + return f"{b['Day'][:3]} {b['FromHour']:02d}:{rev.get(b['FromMinute'], 0):02d}–{b['ToHour']:02d}:{rev.get(b['ToMinute'], 0):02d}" + + +def update_microsoft_campaign_targeting( + config: AdLoopConfig, + *, + ad_account_id: str = "", + campaign_id: str = "", + location_ids: list[str] | None = None, + excluded_location_ids: list[str] | None = None, + location_intent: str = "", + ad_schedule: list[dict] | None = None, +) -> dict: + """Draft targeting changes: included and excluded locations, location intent, ad schedule.""" + operation = "microsoft_update_targeting" + blocked = _guard(operation, config) + if blocked: + return blocked + errors: list[str] = [] + campaign_id = str(campaign_id or "").strip() + if not campaign_id: + errors.append("campaign_id is required") + include = _clean(location_ids) if location_ids is not None else None + exclude = _clean(excluded_location_ids) if excluded_location_ids is not None else None + if include is not None and not include: + errors.append("An empty location list would let the campaign serve everywhere; pass at least one location id.") + if include and exclude and set(include) & set(exclude): + errors.append(f"Location(s) {sorted(set(include) & set(exclude))} cannot be both included and excluded.") + bad_ids = [i for i in (include or []) + (exclude or []) if not i.isdigit()] + if bad_ids: + errors.append(f"Location ids are numbers (search_microsoft_locations); got {bad_ids}.") + intent = (location_intent or "").strip() + if intent and intent not in INTENTS: + errors.append(f"location_intent must be one of {list(INTENTS)}.") + blocks = _schedule_blocks(ad_schedule, errors) if ad_schedule is not None else None + if errors: + return _validation_error(errors) + if include is None and exclude is None and not intent and blocks is None: + return {"error": "Nothing to change: pass location_ids, excluded_location_ids, location_intent or ad_schedule."} + meta, account, customer = _ctx(config, ad_account_id) + found = find_entity(config, account, customer, "campaign", campaign_id) + if not found: + return {"error": f"Microsoft campaign '{campaign_id}' was not found in account {account}."} + campaign = found["entity"] + current = _current_targeting(config, account, customer, campaign_id) + names: dict[str, str] = {} + try: + from adloop.microsoft_ads.read import _GEO_CACHE, location_names + + if _GEO_CACHE.get("rows"): + names = location_names(_GEO_CACHE["rows"], (include or []) + (exclude or [])) + except Exception: # noqa: BLE001 — names are a convenience + names = {} + label = lambda i: names.get(i) or current["included"].get(i, {}).get("name") or current["excluded"].get(i, {}).get("name") or f"id {i}" # noqa: E731 + plan_ops: dict[str, Any] = {"add": [], "delete": [], "update": [], + "schedule_add_first": [], "schedule_delete": [], "schedule_add_after": []} + shown: dict[str, Any] = {} + warnings: list[str] = [] + if include is not None: + add = [i for i in include if i not in current["included"]] + drop = [current["included"][i]["criterion_id"] for i in current["included"] if i not in include] + plan_ops["add"] += [{"Type": "BiddableCampaignCriterion", "CampaignId": campaign_id, + "Criterion": {"Type": "LocationCriterion", "LocationId": int(i)}, + "CriterionBid": {"Type": "BidMultiplier", "Multiplier": 0}} for i in add] + plan_ops["delete"] += drop + shown["locations"] = {"from": [v["name"] for v in current["included"].values()], + "to": [label(i) for i in include], "added": [label(i) for i in add], + "removed": [current["included"][i]["name"] for i in current["included"] if i not in include]} + if exclude is not None: + add = [i for i in exclude if i not in current["excluded"]] + drop = [current["excluded"][i]["criterion_id"] for i in current["excluded"] if i not in exclude] + plan_ops["add"] += [{"Type": "NegativeCampaignCriterion", "CampaignId": campaign_id, + "Criterion": {"Type": "LocationCriterion", "LocationId": int(i)}} for i in add] + plan_ops["delete"] += drop + shown["excluded_locations"] = {"from": [v["name"] for v in current["excluded"].values()], + "to": [label(i) for i in exclude]} + if intent and intent != (current["intent"] or {}).get("option"): + item = {"Type": "BiddableCampaignCriterion", "CampaignId": campaign_id, + "Criterion": {"Type": "LocationIntentCriterion", "IntentOption": intent}} + if current["intent"]: + plan_ops["update"].append({**item, "Id": current["intent"]["criterion_id"]}) + else: + plan_ops["add"].append(item) + shown["location_intent"] = {"from": (current["intent"] or {}).get("option") or "PeopleInOrSearchingForOrViewingPages (default)", + "to": intent} + if intent != "PeopleIn": + warnings.append("This intent also reaches people outside the locations who search for or about them.") + if blocks is not None: + steps = _schedule_steps(current["schedule"], blocks, campaign_id) + gap = steps.pop("gap") + plan_ops.update(steps) + # The campaign decides whose clock the hours follow. + searcher_time = bool(campaign.get("AdScheduleUseSearcherTimeZone")) + current["searcher_time_zone"] = searcher_time + zone = "each searcher's own time zone" if searcher_time else f"the account time zone ({meta['time_zone']})" + shown["ad_schedule"] = {"from": [_block_label(b) for b in current["schedule"]] or "all hours", + "to": [_block_label(b) for b in blocks] or "all hours", + "hours_in": zone} + if searcher_time: + warnings.append("This campaign runs its ad schedule in each searcher's own time zone " + "(AdScheduleUseSearcherTimeZone), not the account's: 09:00 means 09:00 where the searcher is.") + else: + warnings.append(f"Ad schedule hours are in the account time zone ({meta['time_zone']}), not the searcher's.") + if blocks and not current["schedule"]: + warnings.append("The campaign serves at all hours today; this schedule switches every other hour off.") + if gap: + warnings.append("Microsoft cannot edit a schedule window, only delete and add one, and windows may not " + "overlap: the old windows are removed before the new ones are added, so for a moment " + "the campaign has no schedule and serves at all hours. If adding the new windows then " + "fails, the apply reports it (PARTIAL_APPLY) and the campaign stays unscheduled until " + "the schedule is added again.") + if not any(v for k, v in plan_ops.items() if k != "schedule_kept"): + return {"error": "Nothing to change: the targeting already matches."} + return _plan( + operation, "campaign", campaign_id, account, + _base_changes(account, customer, entity_name=campaign.get("Name"), changes=shown, operations=plan_ops, + before=current), + warnings=warnings, + double=bool(blocks) and not current["schedule"], + ) + + +# --------------------------------------------------------------------------- +# New campaign +# --------------------------------------------------------------------------- + + +def draft_microsoft_campaign( + config: AdLoopConfig, + *, + ad_account_id: str = "", + name: str = "", + daily_budget: float = 0.0, + bidding_strategy: str = "MaxConversions", + target_cpa: float | None = None, + languages: list[str] | None = None, + location_ids: list[str] | None = None, + excluded_location_ids: list[str] | None = None, + location_intent: str = "PeopleIn", + tracking_url_template: str = "", + final_url_suffix: str = "", +) -> dict: + """Draft a new Search campaign, created PAUSED, with its locations and location intent.""" + from adloop.safety.guards import SafetyViolation, check_budget_cap + + operation = "microsoft_create_campaign" + blocked = _guard(operation, config) + if blocked: + return blocked + errors: list[str] = [] + name = (name or "").strip() + if not name or len(name) > 128: + errors.append("name is required (at most 128 characters).") + try: + budget = round(float(daily_budget), 2) + except (TypeError, ValueError): + budget = 0.0 + if budget <= 0: + errors.append("daily_budget must be a positive amount in the account currency.") + strategy = "MaxConversions" if bidding_strategy == "TargetCpa" else (bidding_strategy or "MaxConversions") + if strategy not in STRATEGIES: + errors.append(f"bidding_strategy must be one of {list(STRATEGIES)}.") + langs = _clean(languages) + if not langs: + errors.append("languages is required, e.g. ['English']: without it ads reach every language.") + include = _clean(location_ids) + if not include: + errors.append("location_ids is required (search_microsoft_locations): an untargeted campaign serves everywhere.") + exclude = _clean(excluded_location_ids) + if any(not i.isdigit() for i in include + exclude): + errors.append("Location ids are numbers (search_microsoft_locations).") + if location_intent not in INTENTS: + errors.append(f"location_intent must be one of {list(INTENTS)}.") + if errors: + return _validation_error(errors) + try: + check_budget_cap(budget, config.safety) + except SafetyViolation as e: + return {"error": str(e)} + meta, account, customer = _ctx(config, ad_account_id) + existing = {str(c.get("Name")).lower() for c in _campaigns(config, account, customer)} + if name.lower() in existing: + return _validation_error([f"A campaign named '{name}' already exists."]) + warnings: list[str] = [] + if strategy == "MaxConversions" and _counted_goals(config, account, customer) == 0: + warnings.append("No active conversion goal counts toward Conversions: MaxConversions would have nothing to optimize for.") + if target_cpa is not None and target_cpa > 0 and budget < 5 * target_cpa: + warnings.append(f"A daily budget below 5× the target CPA ({target_cpa}) gives bidding little to learn from.") + campaign: dict[str, Any] = { + "Name": name, + "BudgetType": "DailyBudgetStandard", + "DailyBudget": budget, + "CampaignType": "Search", + "Languages": langs, + "Status": "Paused", + "TimeZone": meta["time_zone"], + "BiddingScheme": bidding_scheme(strategy, target_cpa=target_cpa, max_cpc=None), + } + if tracking_url_template: + campaign["TrackingUrlTemplate"] = tracking_url_template.strip() + if final_url_suffix: + campaign["FinalUrlSuffix"] = final_url_suffix.strip() + criteria = ( + [{"Type": "BiddableCampaignCriterion", "Criterion": {"Type": "LocationCriterion", "LocationId": int(i)}, + "CriterionBid": {"Type": "BidMultiplier", "Multiplier": 0}} for i in include] + + [{"Type": "NegativeCampaignCriterion", "Criterion": {"Type": "LocationCriterion", "LocationId": int(i)}} + for i in exclude] + + [{"Type": "BiddableCampaignCriterion", + "Criterion": {"Type": "LocationIntentCriterion", "IntentOption": location_intent}}] + ) + return _plan( + operation, "campaign", "", account, + _base_changes( + account, customer, entity_name=name, status_on_create="Paused", daily_budget=budget, + currency=meta["currency"], monthly_maximum=round(budget * 30.4, 2), bidding=_bidding(campaign["BiddingScheme"]), + languages=langs, location_ids=include, excluded_location_ids=exclude, location_intent=location_intent, + time_zone=meta["time_zone"], tracking_url_template=campaign.get("TrackingUrlTemplate"), + final_url_suffix=campaign.get("FinalUrlSuffix"), campaign=campaign, criteria=criteria, + ), + warnings=warnings + [ + "Created paused. Add ad groups, keywords, ads and extensions, then enable it.", + ], + ) + + +# --------------------------------------------------------------------------- +# Ad groups and keywords +# --------------------------------------------------------------------------- + + +def _keyword_rows(keywords: list, errors: list[str], *, default_match: str = "Phrase") -> list[dict]: + rows = [] + for i, k in enumerate(keywords or []): + if isinstance(k, str): + k = {"text": k} + if not isinstance(k, dict): + errors.append(f"keywords[{i}] must be text or {{text, match_type, bid}}.") + continue + text = str(k.get("text") or "").strip() + match = str(k.get("match_type") or default_match).strip().title() + if not text or len(text) > 100: + errors.append(f"keywords[{i}] text is 1–100 characters.") + if match not in MATCH_TYPES: + errors.append(f"keywords[{i}].match_type must be one of {list(MATCH_TYPES)}.") + row: dict[str, Any] = {"Text": text, "MatchType": match, "Status": "Active"} + if k.get("bid") is not None: + row["Bid"] = {"Amount": round(float(k["bid"]), 2)} + rows.append(row) + return rows + + +def _active_broad_keywords(config, account: str, customer: str, campaign_id: str) -> list[dict]: + return [ + k for g in _ad_groups(config, account, customer, campaign_id) + for k in _keywords(config, account, customer, str(g.get("Id"))) + if k.get("MatchType") == "Broad" and k.get("Status") == "Active" + ] + + +def _check_bid(current: float | None, proposed: float | None, config) -> None: + """Bid-increase cap against the current effective bid (raises SafetyViolation).""" + from adloop.safety.guards import check_bid_increase + + if current and proposed is not None: + check_bid_increase(float(current), float(proposed), config.safety) + + +def _refuse_broad_on_manual(rows: list[dict], campaign: dict, errors: list[str]) -> None: + strategy = _strategy_name(campaign.get("BiddingScheme")) + broad = [r["Text"] for r in rows if r["MatchType"] == "Broad"] + if broad and strategy not in _SMART: + errors.append( + f"Broad match on a {strategy or 'manual'}-bid campaign wastes spend; use Phrase or Exact for " + f"{broad[:5]}, or move the campaign to MaxConversions first." + ) + + +def draft_microsoft_ad_group( + config: AdLoopConfig, + *, + ad_account_id: str = "", + campaign_id: str = "", + name: str = "", + cpc_bid: float | None = None, + network: str = "OwnedAndOperatedOnly", + keywords: list | None = None, +) -> dict: + """Draft a new ad group (with optional keywords) in a campaign.""" + operation = "microsoft_create_ad_group" + blocked = _guard(operation, config) + if blocked: + return blocked + errors: list[str] = [] + name = (name or "").strip() + if not name or len(name) > 256: + errors.append("name is required (at most 256 characters).") + if network not in NETWORKS: + errors.append(f"network must be one of {list(NETWORKS)}.") + rows = _keyword_rows(keywords or [], errors) + if errors: + return _validation_error(errors) + meta, account, customer = _ctx(config, ad_account_id) + found = find_entity(config, account, customer, "campaign", str(campaign_id)) + if not found: + return {"error": f"Microsoft campaign '{campaign_id}' was not found in account {account}."} + campaign = found["entity"] + strategy = _strategy_name(campaign.get("BiddingScheme")) + if strategy in _MANUAL and cpc_bid is None: + errors.append(f"A {strategy} campaign needs cpc_bid for the ad group.") + _refuse_broad_on_manual(rows, campaign, errors) + names = {str(g.get("Name")).lower() for g in _ad_groups(config, account, customer, str(campaign_id))} + if name.lower() in names: + errors.append(f"The campaign already has an ad group named '{name}'.") + if errors: + return _validation_error(errors) + group: dict[str, Any] = {"Name": name, "Network": network, "Status": "Active"} + if cpc_bid is not None: + group["CpcBid"] = {"Amount": round(float(cpc_bid), 2)} + warnings = ["The ad group is active but serves only once an ad in it is enabled (new ads are created paused)."] + if network == "OwnedAndOperatedAndSyndicatedSearch": + warnings.append("Syndicated search partners are included; their traffic is usually weaker.") + return _plan( + operation, "ad_group", "", account, + _base_changes(account, customer, entity_name=name, campaign_id=str(campaign_id), campaign_name=campaign.get("Name"), + campaign_status=campaign.get("Status"), cpc_bid=_money(group.get("CpcBid")), network=network, + status_on_create="Active (its keywords too); nothing serves until an ad in it is enabled", + currency=meta["currency"], + keywords=[f"{r['Text']} [{r['MatchType']}]" + (f" bid {r['Bid']['Amount']}" if r.get("Bid") else "") + for r in rows], + ad_group=group, keyword_rows=rows), + warnings=warnings, + ) + + +def update_microsoft_ad_group( + config: AdLoopConfig, + *, + ad_account_id: str = "", + ad_group_id: str = "", + name: str = "", + cpc_bid: float | None = None, + network: str = "", + audience_ads_bid_adjustment: int | None = None, +) -> dict: + """Draft ad group changes: name, default bid, search network, Audience Network bid adjustment.""" + from adloop.safety.guards import SafetyViolation, check_bid_increase + + operation = "microsoft_update_ad_group" + blocked = _guard(operation, config) + if blocked: + return blocked + errors: list[str] = [] + if network and network not in NETWORKS: + errors.append(f"network must be one of {list(NETWORKS)}.") + if audience_ads_bid_adjustment is not None and not -100 <= int(audience_ads_bid_adjustment) <= 900: + errors.append("audience_ads_bid_adjustment is -100 (off) to 900.") + if errors: + return _validation_error(errors) + meta, account, customer = _ctx(config, ad_account_id) + found = find_entity(config, account, customer, "ad_group", str(ad_group_id)) + if not found: + return {"error": f"Microsoft ad group '{ad_group_id}' was not found in account {account}."} + group, campaign = found["entity"], found["campaign"] + update: dict[str, Any] = {"Id": str(ad_group_id)} + shown: dict[str, Any] = {} + touched: list[str] = [] + warnings: list[str] = [] + if name and name.strip() != group.get("Name"): + update["Name"] = name.strip() + shown["name"] = {"from": group.get("Name"), "to": name.strip()} + touched.append("Name") + if cpc_bid is not None: + old = _money(group.get("CpcBid")) + try: + if old: + check_bid_increase(old, float(cpc_bid), config.safety) + except SafetyViolation as e: + return {"error": str(e)} + update["CpcBid"] = {"Amount": round(float(cpc_bid), 2)} + shown["cpc_bid"] = {"from": old, "to": round(float(cpc_bid), 2), "currency": meta["currency"]} + touched.append("CpcBid") + if _strategy_name(campaign.get("BiddingScheme")) in _SMART: + warnings.append("The campaign uses automated bidding, which ignores the ad group's default bid.") + if network and network != group.get("Network"): + update["Network"] = network + shown["network"] = {"from": group.get("Network"), "to": network} + touched.append("Network") + adjust = None + if audience_ads_bid_adjustment is not None and int(audience_ads_bid_adjustment) != group.get("AudienceAdsBidAdjustment"): + adjust = int(audience_ads_bid_adjustment) + update["AudienceAdsBidAdjustment"] = adjust + shown["audience_network"] = {"from": group.get("AudienceAdsBidAdjustment"), "to": adjust, + "meaning": "off" if adjust == -100 else f"{adjust:+d}% bids on the Audience Network"} + touched.append("AudienceAdsBidAdjustment") + if len(update) == 1: + return {"error": "Nothing to change: pass at least one setting that differs from the ad group."} + return _plan( + operation, "ad_group", str(ad_group_id), account, + _base_changes(account, customer, entity_name=group.get("Name"), campaign_id=str(campaign.get("Id")), + campaign_name=campaign.get("Name"), changes=shown, update=update, + update_audience_adjustment=adjust is not None, + before={k: copy.deepcopy(group.get(k)) for k in sorted(set(touched))}), + warnings=warnings, + ) + + +def draft_microsoft_keywords( + config: AdLoopConfig, *, ad_account_id: str = "", ad_group_id: str = "", keywords: list | None = None, +) -> dict: + """Draft keyword additions to an ad group (duplicates skipped, broad refused on manual bids).""" + operation = "microsoft_add_keywords" + blocked = _guard(operation, config) + if blocked: + return blocked + errors: list[str] = [] + rows = _keyword_rows(keywords or [], errors) + if not rows and not errors: + errors.append("keywords needs at least one keyword.") + if errors: + return _validation_error(errors) + meta, account, customer = _ctx(config, ad_account_id) + found = find_entity(config, account, customer, "ad_group", str(ad_group_id)) + if not found: + return {"error": f"Microsoft ad group '{ad_group_id}' was not found in account {account}."} + group, campaign = found["entity"], found["campaign"] + _refuse_broad_on_manual(rows, campaign, errors) + if errors: + return _validation_error(errors) + existing = {(str(k.get("Text")).lower(), k.get("MatchType")) for k in _keywords(config, account, customer, str(ad_group_id)) + if k.get("Status") != "Deleted"} + seen: set = set() + new_rows, skipped = [], [] + for r in rows: + key = (r["Text"].lower(), r["MatchType"]) + if key in existing or key in seen: + skipped.append(f"{r['Text']} [{r['MatchType']}]") + continue + seen.add(key) + new_rows.append(r) + if not new_rows: + return {"error": "Every keyword is already in the ad group.", "skipped": skipped} + warnings = [f"Skipped, already in the ad group: {skipped}."] if skipped else [] + if group.get("Status") != "Active" or campaign.get("Status") != "Active": + warnings.append(f"The ad group is {group.get('Status')} and the campaign {campaign.get('Status')}: the keywords serve once both are active.") + else: + # Keywords are created Active, as Google Ads keywords are: in a live + # ad group they can serve the moment this is applied. + warnings.append("The keywords are added Active and the ad group and campaign are active, so they can serve " + "as soon as this is applied (once the ad group has an enabled ad).") + return _plan( + operation, "ad_group", str(ad_group_id), account, + _base_changes(account, customer, entity_name=group.get("Name"), campaign_name=campaign.get("Name"), + status_on_create="Active", ad_group_status=group.get("Status"), + campaign_status=campaign.get("Status"), + keywords=[f"{r['Text']} [{r['MatchType']}]" + (f" bid {r['Bid']['Amount']}" if r.get("Bid") else "") + for r in new_rows], + keyword_rows=new_rows), + warnings=warnings, + ) + + +def update_microsoft_keyword_bids( + config: AdLoopConfig, *, ad_account_id: str = "", ad_group_id: str = "", bids: list | None = None, +) -> dict: + """Draft keyword bid changes in one ad group (capped by max_bid_increase_pct).""" + from adloop.safety.guards import SafetyViolation + + operation = "microsoft_update_keyword_bids" + blocked = _guard(operation, config) + if blocked: + return blocked + errors: list[str] = [] + wanted: dict[str, float | None] = {} + for i, b in enumerate(bids or []): + if not isinstance(b, dict) or not b.get("keyword_id"): + errors.append(f"bids[{i}] needs keyword_id and bid (null removes the keyword's own bid).") + continue + wanted[str(b["keyword_id"])] = None if b.get("bid") is None else round(float(b["bid"]), 2) + if not wanted and not errors: + errors.append("bids needs at least one {keyword_id, bid}.") + if errors: + return _validation_error(errors) + meta, account, customer = _ctx(config, ad_account_id) + found = find_entity(config, account, customer, "ad_group", str(ad_group_id)) + if not found: + return {"error": f"Microsoft ad group '{ad_group_id}' was not found in account {account}."} + group = found["entity"] + keywords = {str(k.get("Id")): k for k in _keywords(config, account, customer, str(ad_group_id))} + missing = [k for k in wanted if k not in keywords] + if missing: + return _validation_error([f"Keyword(s) {missing} are not in ad group '{group.get('Name')}'."]) + default_bid = _money(group.get("CpcBid")) + rows, shown, before = [], [], {} + for kid, bid in wanted.items(): + current = _money(keywords[kid].get("Bid")) or default_bid + # Removing a keyword's own bid makes it inherit the ad group default: + # that is a bid change too, and it is capped the same way. + effective = bid if bid is not None else default_bid + try: + _check_bid(current, effective, config) + except SafetyViolation as e: + return {"error": f"{keywords[kid].get('Text')}: {e}"} + rows.append({"Id": kid, "Bid": {"Amount": bid}}) + shown.append({"keyword": f"{keywords[kid].get('Text')} [{keywords[kid].get('MatchType')}]", + "from": current, "to": bid if bid is not None else f"ad group default {default_bid}"}) + before[kid] = copy.deepcopy(keywords[kid].get("Bid")) + return _plan( + operation, "ad_group", str(ad_group_id), account, + _base_changes(account, customer, entity_name=group.get("Name"), currency=meta["currency"], bids=shown, + keyword_rows=rows, before=before, default_bid_before=copy.deepcopy(group.get("CpcBid"))), + ) + + +# --------------------------------------------------------------------------- +# Negative keywords: direct and shared lists +# --------------------------------------------------------------------------- + + +def _negative_rows(keywords: list, match_type: str, errors: list[str]) -> list[dict]: + match = (match_type or "Phrase").strip().title() + if match not in NEGATIVE_MATCH_TYPES: + errors.append(f"match_type for negatives must be one of {list(NEGATIVE_MATCH_TYPES)}.") + rows, seen = [], set() + for text in _clean(keywords): + if len(text) > 100: + errors.append(f"Negative '{text[:20]}…' is longer than 100 characters.") + if text.lower() not in seen: + seen.add(text.lower()) + rows.append({"Text": text, "MatchType": match}) + if not rows and not errors: + errors.append("keywords needs at least one negative keyword.") + return rows + + +def _entity_negatives(config: AdLoopConfig, account: str, customer: str, entity_type: str, entity_id: str, + parent_id: str = "") -> list[dict]: + payload = campaign_request( + config, "NegativeKeywords/QueryByEntityIds", + {"EntityIds": [int(entity_id)], "EntityType": entity_type, "ParentEntityId": int(parent_id) if parent_id else None}, + account_id=account, customer_id=customer, + ) + out = [] + for entry in payload.get("EntityNegativeKeywords") or []: + out.extend(n for n in (entry or {}).get("NegativeKeywords") or [] if isinstance(n, dict)) + return out + + +def _shared_lists(config: AdLoopConfig, account: str, customer: str) -> list[dict]: + payload = campaign_request( + config, "SharedEntities/Query", {"SharedEntityType": _LIST_TYPE, "SharedEntityScope": "Account"}, + account_id=account, customer_id=customer, + ) + return [e for e in payload.get("SharedEntities") or [] if isinstance(e, dict)] + + +def _list_items(config: AdLoopConfig, account: str, customer: str, list_id: str) -> list[dict]: + payload = campaign_request( + config, "ListItems/QueryBySharedList", + {"SharedList": {"Type": _LIST_TYPE, "Id": int(list_id)}, "SharedEntityScope": "Account"}, + account_id=account, customer_id=customer, + ) + return [i for i in payload.get("ListItems") or [] if isinstance(i, dict)] + + +def _list_associations(config: AdLoopConfig, account: str, customer: str, campaign_ids: list[str]) -> list[dict]: + out = [] + for chunk in _chunks([int(c) for c in campaign_ids]): + payload = campaign_request( + config, "SharedEntityAssociations/QueryByEntityIds", + {"EntityIds": chunk, "EntityType": "Campaign", "SharedEntityType": _LIST_TYPE, "SharedEntityScope": "Account"}, + account_id=account, customer_id=customer, + ) + out.extend(a for a in payload.get("Associations") or [] if isinstance(a, dict)) + return out + + +def _positive_conflicts(config: AdLoopConfig, account: str, customer: str, campaign_ids: list[str], rows: list[dict]) -> list[str]: + texts = {r["Text"].lower(): r for r in rows} + hits = [] + for cid in campaign_ids: + for g in _ad_groups(config, account, customer, cid): + for k in _keywords(config, account, customer, str(g.get("Id"))): + text = str(k.get("Text") or "").lower() + if k.get("Status") == "Active" and text in texts: + hits.append(f"'{k.get('Text')}' ({g.get('Name')})") + return hits + + +def get_microsoft_negative_keywords(config: AdLoopConfig, *, ad_account_id: str = "", campaign_id: str = "") -> dict: + """Negative keywords of the account's campaigns: direct ones and shared lists with their items.""" + meta, account, customer = _ctx(config, ad_account_id) + campaigns = [c for c in _campaigns(config, account, customer) if not campaign_id or str(c.get("Id")) == str(campaign_id)] + direct = [] + for c in campaigns: + for n in _entity_negatives(config, account, customer, "Campaign", str(c.get("Id"))): + direct.append({"campaign_id": str(c.get("Id")), "campaign_name": c.get("Name"), "text": n.get("Text"), + "match_type": n.get("MatchType"), + "remove_id": f"Campaign~{c.get('Id')}~{n.get('Id')}"}) + lists = _shared_lists(config, account, customer) + associations = _list_associations(config, account, customer, [str(c.get("Id")) for c in campaigns]) if campaigns else [] + names = {str(c.get("Id")): c.get("Name") for c in campaigns} + attached: dict[str, list[str]] = {} + for a in associations: + attached.setdefault(str(a.get("SharedEntityId")), []).append(names.get(str(a.get("EntityId")), str(a.get("EntityId")))) + shared = [] + for lst in lists: + lid = str(lst.get("Id")) + if campaign_id and lid not in attached: + continue + items = _list_items(config, account, customer, lid) + shared.append({ + "list_id": lid, "name": lst.get("Name"), "item_count": lst.get("ItemCount", len(items)), + "attached_to": attached.get(lid, []), + "keywords": [{"text": i.get("Text"), "match_type": i.get("MatchType"), "remove_id": f"{lid}~{i.get('Id')}"} + for i in items], + }) + insights = [] + if direct: + insights.append(f"{len(direct)} negative(s) sit directly on campaigns; a shared list keeps them reusable across campaigns.") + unattached = [s["name"] for s in shared if not s["attached_to"]] + if unattached and not campaign_id: + insights.append(f"Lists attached to no campaign: {unattached}.") + return {"ad_account_id": account, "direct_negatives": direct, "negative_keyword_lists": shared, "insights": insights} + + +def add_microsoft_negative_keywords( + config: AdLoopConfig, *, ad_account_id: str = "", campaign_id: str = "", ad_group_id: str = "", + keywords: list | None = None, match_type: str = "Phrase", +) -> dict: + """Draft negatives directly on one campaign or ad group.""" + operation = "microsoft_add_negative_keywords" + blocked = _guard(operation, config) + if blocked: + return blocked + errors: list[str] = [] + if bool(campaign_id) == bool(ad_group_id): + errors.append("Pass exactly one of campaign_id or ad_group_id.") + rows = _negative_rows(keywords or [], match_type, errors) + if errors: + return _validation_error(errors) + meta, account, customer = _ctx(config, ad_account_id) + kind = "campaign" if campaign_id else "ad_group" + found = find_entity(config, account, customer, kind, str(campaign_id or ad_group_id)) + if not found: + return {"error": f"Microsoft {kind.replace('_', ' ')} '{campaign_id or ad_group_id}' was not found."} + entity, campaign = found["entity"], found["campaign"] + entity_type = "Campaign" if kind == "campaign" else "AdGroup" + existing = {(str(n.get("Text")).lower(), n.get("MatchType")) for n in _entity_negatives( + config, account, customer, entity_type, str(entity.get("Id")), "" if kind == "campaign" else str(campaign.get("Id")))} + new_rows = [r for r in rows if (r["Text"].lower(), r["MatchType"]) not in existing] + if not new_rows: + return {"error": "Every negative is already there."} + warnings = ["A shared negative keyword list (propose_microsoft_negative_keyword_list) keeps negatives reusable across campaigns."] + conflicts = _positive_conflicts(config, account, customer, [str(campaign.get("Id"))], new_rows) + if conflicts: + warnings.append(f"These negatives block active keywords: {conflicts[:10]}.") + return _plan( + operation, kind, str(entity.get("Id")), account, + _base_changes(account, customer, entity_name=entity.get("Name"), entity_kind=entity_type, + parent_id=str(campaign.get("Id")), + negatives=[f"{r['Text']} [{r['MatchType']}]" for r in new_rows], negative_rows=new_rows), + warnings=warnings, + ) + + +def propose_microsoft_negative_keyword_list( + config: AdLoopConfig, *, ad_account_id: str = "", list_name: str = "", keywords: list | None = None, + match_type: str = "Phrase", campaign_ids: list[str] | None = None, +) -> dict: + """Draft a new shared negative keyword list and attach it to campaigns.""" + operation = "microsoft_create_negative_list" + blocked = _guard(operation, config) + if blocked: + return blocked + errors: list[str] = [] + list_name = (list_name or "").strip() + if not list_name or len(list_name) > 255: + errors.append("list_name is required (at most 255 characters).") + rows = _negative_rows(keywords or [], match_type, errors) + if len(rows) > 5000: + errors.append("At most 5,000 negatives in one draft.") + cids = _clean(campaign_ids) + if errors: + return _validation_error(errors) + meta, account, customer = _ctx(config, ad_account_id) + if list_name.lower() in {str(lst.get("Name")).lower() for lst in _shared_lists(config, account, customer)}: + return _validation_error([f"A negative keyword list named '{list_name}' already exists; add_to_microsoft_negative_keyword_list appends to it."]) + campaigns = {str(c.get("Id")): c for c in _campaigns(config, account, customer)} + unknown = [c for c in cids if c not in campaigns] + if unknown: + return _validation_error([f"Campaign(s) {unknown} are not in account {account}."]) + warnings = [] + if cids: + counts: dict[str, int] = {} + for a in _list_associations(config, account, customer, cids): + counts[str(a.get("EntityId"))] = counts.get(str(a.get("EntityId")), 0) + 1 + full = [campaigns[c].get("Name") for c in cids if counts.get(c, 0) >= _MAX_LISTS_PER_CAMPAIGN] + if full: + return _validation_error([f"Campaign(s) {full} already have {_MAX_LISTS_PER_CAMPAIGN} lists, Microsoft's limit."]) + conflicts = _positive_conflicts(config, account, customer, cids, rows) + if conflicts: + warnings.append(f"These negatives block active keywords: {conflicts[:10]}.") + else: + warnings.append("The list is attached to no campaign, so it blocks nothing until attached.") + return _plan( + operation, "negative_keyword_list", "", account, + _base_changes(account, customer, entity_name=list_name, negatives=[f"{r['Text']} [{r['MatchType']}]" for r in rows], + attach_to=[campaigns[c].get("Name") for c in cids], campaign_ids=cids, negative_rows=rows), + warnings=warnings, + ) + + +def add_to_microsoft_negative_keyword_list( + config: AdLoopConfig, *, ad_account_id: str = "", list_id: str = "", keywords: list | None = None, + match_type: str = "Phrase", +) -> dict: + """Draft appending negatives to an existing shared list (items already there are skipped).""" + operation = "microsoft_add_to_negative_list" + blocked = _guard(operation, config) + if blocked: + return blocked + errors: list[str] = [] + rows = _negative_rows(keywords or [], match_type, errors) + if errors: + return _validation_error(errors) + meta, account, customer = _ctx(config, ad_account_id) + lists = {str(lst.get("Id")): lst for lst in _shared_lists(config, account, customer)} + if str(list_id) not in lists: + return {"error": f"Negative keyword list '{list_id}' was not found (get_microsoft_negative_keywords lists them)."} + items = _list_items(config, account, customer, str(list_id)) + have = {(str(i.get("Text")).lower(), i.get("MatchType")) for i in items} + new_rows = [r for r in rows if (r["Text"].lower(), r["MatchType"]) not in have] + if not new_rows: + return {"error": "Every negative is already in the list."} + attached = [str(a.get("EntityId")) for a in _list_associations( + config, account, customer, [str(c.get("Id")) for c in _campaigns(config, account, customer)]) + if str(a.get("SharedEntityId")) == str(list_id)] + warnings = [] + conflicts = _positive_conflicts(config, account, customer, attached, new_rows) + if conflicts: + warnings.append(f"These negatives block active keywords: {conflicts[:10]}.") + return _plan( + operation, "negative_keyword_list", str(list_id), account, + _base_changes(account, customer, entity_name=lists[str(list_id)].get("Name"), attached_campaigns=len(attached), + negatives=[f"{r['Text']} [{r['MatchType']}]" for r in new_rows], negative_rows=new_rows), + warnings=warnings, + ) + + +def _draft_list_link(config, *, attach: bool, ad_account_id: str, list_id: str, campaign_ids: list | None) -> dict: + operation = "microsoft_attach_negative_list" if attach else "microsoft_detach_negative_list" + blocked = _guard(operation, config) + if blocked: + return blocked + cids = _clean(campaign_ids) + if not cids: + return _validation_error(["campaign_ids needs at least one campaign id."]) + meta, account, customer = _ctx(config, ad_account_id) + lists = {str(lst.get("Id")): lst for lst in _shared_lists(config, account, customer)} + if str(list_id) not in lists: + return {"error": f"Negative keyword list '{list_id}' was not found."} + campaigns = {str(c.get("Id")): c for c in _campaigns(config, account, customer)} + unknown = [c for c in cids if c not in campaigns] + if unknown: + return _validation_error([f"Campaign(s) {unknown} are not in account {account}."]) + linked = {str(a.get("EntityId")) for a in _list_associations(config, account, customer, cids) + if str(a.get("SharedEntityId")) == str(list_id)} + targets = [c for c in cids if (c not in linked) == attach] + if not targets: + return {"error": "Nothing to change: every campaign is already " + ("attached." if attach else "detached.")} + warnings = [] + if not attach: + warnings.append("Detached campaigns stop blocking these negatives; the list itself stays.") + return _plan( + operation, "negative_keyword_list", str(list_id), account, + _base_changes(account, customer, entity_name=lists[str(list_id)].get("Name"), + campaigns=[campaigns[c].get("Name") for c in targets], campaign_ids=targets), + warnings=warnings, + ) + + +def attach_microsoft_negative_keyword_list(config, *, ad_account_id="", list_id="", campaign_ids=None) -> dict: + return _draft_list_link(config, attach=True, ad_account_id=ad_account_id, list_id=list_id, campaign_ids=campaign_ids) + + +def detach_microsoft_negative_keyword_list(config, *, ad_account_id="", list_id="", campaign_ids=None) -> dict: + return _draft_list_link(config, attach=False, ad_account_id=ad_account_id, list_id=list_id, campaign_ids=campaign_ids) + + +# --------------------------------------------------------------------------- +# Responsive search ads +# --------------------------------------------------------------------------- + + +def _assets(items: list, limit: int, slots: tuple, field: str, errors: list[str]) -> list[dict]: + links = [] + for i, item in enumerate(items or []): + text, pin = (item.get("text"), item.get("pinned_field")) if isinstance(item, dict) else (item, None) + text = str(text or "").strip() + if not text or len(text) > limit: + errors.append(f"{field}[{i}] is 1–{limit} characters (got {len(text)}): '{text}'.") + link: dict[str, Any] = {"Asset": {"Type": "TextAsset", "Text": text}} + if pin: + normalized = _PINS.get(str(pin).strip().lower().replace(" ", "_")) + if normalized not in slots: + errors.append(f"{field}[{i}].pinned_field must be one of {list(slots)}.") + link["PinnedField"] = normalized + links.append(link) + texts = [l["Asset"]["Text"].lower() for l in links] + if len(set(texts)) != len(texts): + errors.append(f"{field} repeat the same text.") + for slot in slots: + pinned = [l for l in links if l.get("PinnedField") == slot] + unpinned = [l for l in links if not l.get("PinnedField")] + if not pinned and not unpinned: + errors.append(f"Nothing can fill {slot}: pin an asset there or leave some unpinned.") + return links + + +def _rsa_fields(headlines, descriptions, final_url, path1, path2, errors, warnings, *, partial: bool) -> dict: + fields: dict[str, Any] = {} + if headlines is not None or not partial: + h = _assets(headlines or [], 30, ("Headline1", "Headline2", "Headline3"), "headlines", errors) + if not 3 <= len(h) <= 15: + errors.append(f"An RSA takes 3–15 headlines (got {len(h)}).") + fields["Headlines"] = h + if descriptions is not None or not partial: + d = _assets(descriptions or [], 90, ("Description1", "Description2"), "descriptions", errors) + if not 2 <= len(d) <= 4: + errors.append(f"An RSA takes 2–4 descriptions (got {len(d)}).") + fields["Descriptions"] = d + if final_url or not partial: + _check_url((final_url or "").strip(), errors, warnings) + fields["FinalUrls"] = [(final_url or "").strip()] + for name, value in (("Path1", path1), ("Path2", path2)): + if value is None: + continue + value = value.strip() + if len(value) > 15 or "/" in value: + errors.append(f"{name.lower()} is at most 15 characters, without '/'.") + fields[name] = value + if fields.get("Path2") and not (fields.get("Path1") or (partial and path1 is None)): + errors.append("path2 needs path1.") + if not partial and fields.get("Headlines") and len(fields["Headlines"]) < 8: + warnings.append("8–15 distinct headlines give Microsoft more combinations to test.") + pins = [l for l in fields.get("Headlines", []) + fields.get("Descriptions", []) if l.get("PinnedField")] + if pins: + warnings.append(f"{len(pins)} asset(s) are pinned; pinning limits the combinations Microsoft can show.") + return fields + + +def draft_microsoft_responsive_search_ad( + config: AdLoopConfig, *, ad_account_id: str = "", ad_group_id: str = "", headlines: list | None = None, + descriptions: list | None = None, final_url: str = "", path1: str = "", path2: str = "", +) -> dict: + """Draft a responsive search ad, created PAUSED.""" + operation = "microsoft_create_rsa" + blocked = _guard(operation, config) + if blocked: + return blocked + errors: list[str] = [] + warnings: list[str] = [] + fields = _rsa_fields(headlines, descriptions, final_url, path1, path2, errors, warnings, partial=False) + if errors: + return _validation_error(errors) + meta, account, customer = _ctx(config, ad_account_id) + found = find_entity(config, account, customer, "ad_group", str(ad_group_id)) + if not found: + return {"error": f"Microsoft ad group '{ad_group_id}' was not found in account {account}."} + group, campaign = found["entity"], found["campaign"] + ad = {"Type": "ResponsiveSearch", "Status": "Paused", **fields} + for key in ("Path1", "Path2"): + if not ad.get(key): + ad.pop(key, None) + if "Path1" not in ad: + ad.pop("Path2", None) + warnings.append("No display paths: path1/path2 make the display URL more specific.") + return _plan( + operation, "ad_group", str(ad_group_id), account, + _base_changes(account, customer, entity_name=group.get("Name"), campaign_name=campaign.get("Name"), + status_on_create="Paused", + headlines=[l["Asset"]["Text"] + (f" [pinned {l['PinnedField']}]" if l.get("PinnedField") else "") for l in fields["Headlines"]], + descriptions=[l["Asset"]["Text"] for l in fields["Descriptions"]], + final_url=fields["FinalUrls"][0], path1=ad.get("Path1"), path2=ad.get("Path2"), ad=ad), + warnings=warnings, + ) + + +def update_microsoft_responsive_search_ad( + config: AdLoopConfig, *, ad_account_id: str = "", ad_id: str = "", headlines: list | None = None, + descriptions: list | None = None, final_url: str = "", path1: str | None = None, path2: str | None = None, +) -> dict: + """Draft RSA changes: headlines or descriptions (each list replaced whole), landing page, paths.""" + operation = "microsoft_update_rsa" + blocked = _guard(operation, config) + if blocked: + return blocked + errors: list[str] = [] + warnings: list[str] = [] + fields = _rsa_fields(headlines, descriptions, final_url, path1, path2, errors, warnings, partial=True) + if errors: + return _validation_error(errors) + if not fields: + return {"error": "Nothing to change: pass headlines, descriptions, final_url, path1 or path2."} + meta, account, customer = _ctx(config, ad_account_id) + found = find_entity(config, account, customer, "ad", str(ad_id)) + if not found: + return {"error": f"Microsoft ad '{ad_id}' was not found in account {account}."} + ad, group = found["entity"], found["ad_group"] + if ad.get("Type") != "ResponsiveSearch": + return _validation_error([f"Ad {ad_id} is a {ad.get('Type')} ad; only responsive search ads are edited here."]) + shown = {} + for key, value in fields.items(): + if key in ("Headlines", "Descriptions"): + shown[key.lower()] = {"from": [l.get("Asset", {}).get("Text") for l in ad.get(key) or []], + "to": [l["Asset"]["Text"] for l in value]} + else: + shown[key.lower()] = {"from": ad.get(key), "to": value} + warnings.append("Edited ads go back to Microsoft's editorial review.") + return _plan( + operation, "ad", str(ad_id), account, + _base_changes(account, customer, entity_name=f"RSA {ad_id}", ad_group_id=str(group.get("Id")), + ad_group_name=group.get("Name"), changes=shown, + update={"Type": "ResponsiveSearch", "Id": str(ad_id), **fields}, + before={k: copy.deepcopy(ad.get(k)) for k in fields}), + warnings=warnings, + ) + + +# --------------------------------------------------------------------------- +# Ad extensions: sitelinks, callouts, structured snippets, call +# --------------------------------------------------------------------------- + +# The plan's entity_type for each Microsoft AssociationType. +_ASSOCIATION_ENTITY = {"Account": "account", "Campaign": "campaign", "AdGroup": "ad_group"} + + +def _extension_target(config, account, customer, campaign_id: str, scope: str, + ad_group_id: str = "") -> tuple[str, str, str] | dict: + """(AssociationType, entity id, label) of where an extension links; ad groups only when the caller allows them.""" + if scope == "account": + if campaign_id or ad_group_id: + given = "ad_group_id" if ad_group_id else "campaign_id" + return _validation_error([f"Pass {given} or scope='account', not both."]) + return "Account", account, f"account {account}" + if ad_group_id: + if campaign_id: + return _validation_error(["Pass campaign_id or ad_group_id, not both."]) + found = find_entity(config, account, customer, "ad_group", str(ad_group_id)) + if not found: + return {"error": f"Microsoft ad group '{ad_group_id}' was not found in account {account}."} + return ("AdGroup", str(ad_group_id), + f"ad group '{found['entity'].get('Name')}' in campaign '{found['campaign'].get('Name')}'") + if not campaign_id: + return _validation_error(["campaign_id is required (or scope='account' for every campaign without its own)."]) + found = find_entity(config, account, customer, "campaign", str(campaign_id)) + if not found: + return {"error": f"Microsoft campaign '{campaign_id}' was not found in account {account}."} + return "Campaign", str(campaign_id), f"campaign '{found['entity'].get('Name')}'" + + +def _associated_extensions(config, account, customer, association_type: str, entity_id: str | list[str]) -> list[dict]: + """Extension links of one entity or of up to 100 (Microsoft's EntityIds limit); each carries its EntityId.""" + ids = [str(i) for i in (entity_id if isinstance(entity_id, list) else [entity_id])] + body = {"AccountId": account, "AdExtensionType": _EXTENSION_TYPES, "AssociationType": association_type, + "EntityIds": [int(i) for i in ids]} + payload = campaign_request(config, "AdExtensionsAssociations/Query", body, account_id=account, customer_id=customer) + out = [] + # One collection per requested entity, in the request's order. + for owner, collection in zip(ids, payload.get("AdExtensionAssociationCollection") or [], strict=False): + for assoc in (collection or {}).get("AdExtensionAssociations") or []: + if isinstance(assoc, dict) and isinstance(assoc.get("AdExtension"), dict): + out.append({**assoc, "EntityId": str(assoc.get("EntityId") or owner)}) + return out + + +def _draft_extensions(config, *, ad_account_id, campaign_id, scope, operation, kind, extensions, shown, warnings) -> dict: + blocked = _guard(operation, config) + if blocked: + return blocked + meta, account, customer = _ctx(config, ad_account_id) + target = _extension_target(config, account, customer, str(campaign_id or ""), (scope or "").strip().lower()) + if isinstance(target, dict): + return target + association, entity_id, where = target + existing = _associated_extensions(config, account, customer, association, entity_id) + same = [a["AdExtension"] for a in existing if a["AdExtension"].get("Type") == kind] + if kind == "CallAdExtension" and same: + return _validation_error([f"{where} already has a call extension; Microsoft allows one per campaign."]) + def key(ext): # noqa: E306 + return json.dumps({k: ext.get(k) for k in ("Text", "DisplayText", "Header", "Values", "PhoneNumber")}, sort_keys=True).lower() + have = {key(e) for e in same} + new = [e for e in extensions if key(e) not in have] + if not new: + return {"error": f"Every one of these is already on {where}."} + if len(new) < len(extensions): + warnings.append(f"Skipped {len(extensions) - len(new)} already on {where}.") + return _plan( + operation, association.lower(), entity_id, account, + _base_changes(account, customer, entity_name=where, association_type=association, entity_id=entity_id, + **shown, extensions=new), + warnings=warnings, + ) + + +def draft_microsoft_sitelinks(config, *, ad_account_id="", campaign_id="", scope="", sitelinks=None) -> dict: + errors: list[str] = [] + warnings: list[str] = [] + exts = [] + for i, s in enumerate(sitelinks or []): + if not isinstance(s, dict): + errors.append(f"sitelinks[{i}] must be {{link_text, final_url, description1, description2}}.") + continue + text = str(s.get("link_text") or "").strip() + d1, d2 = str(s.get("description1") or "").strip(), str(s.get("description2") or "").strip() + limit = 25 if (d1 or d2) else 35 + if not text or len(text) > limit: + errors.append(f"sitelinks[{i}].link_text is 1–{limit} characters.") + if bool(d1) != bool(d2): + errors.append(f"sitelinks[{i}] needs both descriptions or neither.") + if len(d1) > 35 or len(d2) > 35: + errors.append(f"sitelinks[{i}] descriptions are at most 35 characters each.") + _check_url(str(s.get("final_url") or "").strip(), errors, warnings, field=f"sitelinks[{i}].final_url") + ext = {"Type": "SitelinkAdExtension", "DisplayText": text, "FinalUrls": [str(s.get("final_url") or "").strip()]} + if d1: + ext.update(Description1=d1, Description2=d2) + exts.append(ext) + if not exts and not errors: + errors.append("sitelinks needs at least one sitelink.") + if len(exts) > 20: + errors.append("At most 20 sitelinks per campaign.") + if errors: + return _validation_error(errors) + if len(exts) < 4: + warnings.append("Four or more sitelinks let Microsoft show the larger sitelink formats.") + return _draft_extensions(config, ad_account_id=ad_account_id, campaign_id=campaign_id, scope=scope, + operation="microsoft_add_sitelinks", kind="SitelinkAdExtension", extensions=exts, + shown={"sitelinks": [ + f"{e['DisplayText']} → {e['FinalUrls'][0]}" + + (f" ({e['Description1']} / {e['Description2']})" if e.get("Description1") else "") + for e in exts]}, + warnings=warnings) + + +def draft_microsoft_callouts(config, *, ad_account_id="", campaign_id="", scope="", callouts=None) -> dict: + errors: list[str] = [] + texts = _clean(callouts) + for t in texts: + if len(t) > 25: + errors.append(f"Callout '{t}' is longer than 25 characters.") + if not texts: + errors.append("callouts needs at least one callout.") + if errors: + return _validation_error(errors) + warnings = [] if len(texts) >= 2 else ["A campaign needs at least 2 callouts before Microsoft shows them."] + exts = [{"Type": "CalloutAdExtension", "Text": t} for t in dict.fromkeys(texts)] + return _draft_extensions(config, ad_account_id=ad_account_id, campaign_id=campaign_id, scope=scope, + operation="microsoft_add_callouts", kind="CalloutAdExtension", extensions=exts, + shown={"callouts": [e["Text"] for e in exts]}, warnings=warnings) + + +def draft_microsoft_structured_snippet(config, *, ad_account_id="", campaign_id="", scope="", header="", values=None) -> dict: + errors: list[str] = [] + vals = list(dict.fromkeys(_clean(values))) + if not (header or "").strip(): + errors.append("header is required (one of Microsoft's headers, e.g. Services, Brands, Types).") + if not 3 <= len(vals) <= 10: + errors.append(f"A structured snippet takes 3–10 values (got {len(vals)}).") + for v in vals: + if len(v) > 25: + errors.append(f"Value '{v}' is longer than 25 characters.") + if errors: + return _validation_error(errors) + ext = {"Type": "StructuredSnippetAdExtension", "Header": header.strip(), "Values": vals} + return _draft_extensions(config, ad_account_id=ad_account_id, campaign_id=campaign_id, scope=scope, + operation="microsoft_add_structured_snippet", kind="StructuredSnippetAdExtension", + extensions=[ext], shown={"snippet": f"{ext['Header']}: {', '.join(vals)}"}, warnings=[]) + + +def draft_microsoft_call_extension(config, *, ad_account_id="", campaign_id="", phone_number="", country_code="") -> dict: + errors: list[str] = [] + number = (phone_number or "").strip() + country = (country_code or "").strip().upper() + if not number or len(number) > 35: + errors.append("phone_number is required (at most 35 characters).") + if len(country) != 2 or not country.isalpha(): + errors.append("country_code is the two-letter country of the number, e.g. US.") + if errors: + return _validation_error(errors) + ext = {"Type": "CallAdExtension", "PhoneNumber": number, "CountryCode": country, "IsCallOnly": False} + return _draft_extensions(config, ad_account_id=ad_account_id, campaign_id=campaign_id, scope="", + operation="microsoft_add_call_extension", kind="CallAdExtension", extensions=[ext], + shown={"phone_number": number, "country_code": country}, + warnings=["Use the call-tracking number that should receive Microsoft calls."]) + + +# --------------------------------------------------------------------------- +# Image extensions +# --------------------------------------------------------------------------- +# Microsoft's limits, from its documentation (checked 2026-11-05): +# [EXT] ImageAdExtension: learn.microsoft.com/advertising/campaign-management-service/imageadextension +# [IMG] Image (media): learn.microsoft.com/advertising/campaign-management-service/image +# [ADD] AddMedia: learn.microsoft.com/advertising/campaign-management-service/addmedia +# [RSA] ResponsiveAd Remarks (same media library): +# learn.microsoft.com/advertising/campaign-management-service/responsivead#remarks +# [BULK] Image Ad Extension record: learn.microsoft.com/advertising/bulk-service/image-ad-extension +# [HELP] Add images to your ad with image extensions: +# learn.microsoft.com/advertising/msa-help/hlp_ba_proc_addimageextension +# [GUIDE] Image guidelines and policies: learn.microsoft.com/advertising/msa-help/hlp_ba_conc_imageguidelines +# [AUD] Audience ads guide: learn.microsoft.com/advertising/guides/audience-ads + +# GIF, JPEG and PNG, no animation [IMG Remarks, GUIDE]. +_IMAGE_FORMATS = {"image/jpeg": "JPEG", "image/png": "PNG", "image/gif": "GIF"} +# "1.91:1 aspect ratio is required for the extension to be eligible to serve" +# with a minimum of 703 x 368 pixels [GUIDE, HELP]; Microsoft crops the other +# placements' ratios from it. The extension links the image as its +# LandscapeImageMedia asset, which is 1.91:1 [BULK images.subType]. +_IMAGE_RATIO = 1.91 +_IMAGE_RATIO_TOLERANCE = 0.01 # 1200x628 is 1.911, 703x368 is 1.910 +_IMAGE_MIN_SIZE = (703, 368) +# "The maximum width and height in pixels are 2592 and 2048 independently" [IMG, RSA]. +_IMAGE_MAX_SIZE = (2592, 2048) +# "The maximum file size is 5 MB" [RSA Remarks]. [IMG] also names a cap of +# 102,400 base64 characters (about 75 KB) for Image.Data, but Microsoft does +# not enforce it on upload: JPEGs of 125-300 KB went through on a live +# account. The draft enforces the 5 MB limit only. +_IMAGE_MAX_BYTES = 5 * 1024 * 1024 +# "You can add a maximum of 10 media in a single call" [ADD]. +_IMAGES_PER_DRAFT = 10 +_ALT_TEXT_MAX = 35 # AlternativeText, required [EXT] +_DISPLAY_TEXT_MAX = 35 # DisplayText, required for the SearchMultiple layout [EXT] +_DESCRIPTION_MAX = 100 # Description, internal label, not shown [EXT] +# Image extensions linked to one account, campaign or ad group: 25 in [BULK] +# and [HELP], 6 in [EXT] and the "About ad extensions" association table. +_IMAGE_LINKS_MAX = 25 +_IMAGE_LINKS_LOW = 6 + + +def _gif_frames(data: bytes) -> int: + """Image frames in a GIF (2 is enough to call it animated).""" + def skip_blocks(i: int) -> int: + while data[i]: + i += data[i] + 1 + return i + 1 + + frames = 0 + try: + flags = data[10] + i = 13 + (3 * 2 ** ((flags & 0x07) + 1) if flags & 0x80 else 0) + while i < len(data) and frames < 2: + block = data[i] + if block == 0x2C: # image descriptor + frames += 1 + flags = data[i + 9] + i += 10 + (3 * 2 ** ((flags & 0x07) + 1) if flags & 0x80 else 0) + i = skip_blocks(i + 1) # LZW minimum code size, then the data + elif block == 0x21: # extension + i = skip_blocks(i + 2) + else: + break + except IndexError: + pass + return frames + + +def _is_animated(data: bytes, mime_type: str) -> bool: + if mime_type == "image/gif": + return _gif_frames(data) > 1 + if mime_type == "image/png": + # An APNG declares its animation (acTL) before the first image data. + actl, idat = data.find(b"acTL"), data.find(b"IDAT") + return actl != -1 and (idat == -1 or actl < idat) + return False + + +def _crop_hint(width: int, height: int) -> str: + if width / height > _IMAGE_RATIO: + return f"{round(height * _IMAGE_RATIO)}x{height}" + return f"{width}x{round(width / _IMAGE_RATIO)}" + + +def _image_problems(label: str, data: bytes, mime_type: str, width: int, height: int) -> list[str]: + """Why Microsoft would refuse this image for an image extension (empty when it fits).""" + problems = [] + if mime_type not in _IMAGE_FORMATS: + problems.append(f"{label}: {mime_type} is not accepted; use JPEG, PNG or GIF.") + elif _is_animated(data, mime_type): + problems.append(f"{label}: animated images are not accepted; use a still image.") + if len(data) > _IMAGE_MAX_BYTES: + problems.append(f"{label}: {len(data) / 1024 / 1024:.1f} MB is over Microsoft's 5 MB limit.") + if width < _IMAGE_MIN_SIZE[0] or height < _IMAGE_MIN_SIZE[1]: + problems.append(f"{label}: {width}x{height} is smaller than Microsoft's minimum of 703x368 for image extensions.") + if width > _IMAGE_MAX_SIZE[0] or height > _IMAGE_MAX_SIZE[1]: + problems.append(f"{label}: {width}x{height} is larger than Microsoft's maximum (width 2592, height 2048); " + "scale it down, e.g. to 1200x628.") + ratio = width / height if height else 0 + if abs(ratio - _IMAGE_RATIO) > _IMAGE_RATIO * _IMAGE_RATIO_TOLERANCE: + problems.append(f"{label}: the aspect ratio is {ratio:.2f}:1; image extensions need 1.91:1 (e.g. 1200x628). " + f"Crop it to {_crop_hint(width, height)} first.") + return problems + + +def _image_label(payload: dict) -> str: + return str(payload.get("url") or payload.get("path") or f"upload {payload.get('upload_id')}") + + +def _draft_images(paths: list[str], urls: list[str], uploads: list[str]) -> tuple[list[dict], list[str]]: + """Load, validate and pin (sha256) every image; the bytes stay out of the plan. + + Loading reuses the Google Ads image tools: image_payloads checks the files + and fetches URLs through the private-address-proof fetcher, and + load_image_bytes reads the approved bytes back. + """ + from adloop.ads.write import image_payloads, load_image_bytes + + payloads, errors = image_payloads(paths, urls, uploads) + images, seen = [], set() + for payload in payloads: + label = _image_label(payload) + try: + data, _name = load_image_bytes(payload) + except Exception as exc: # noqa: BLE001 - a fetch or upload problem is the user's to fix + errors.append(f"{label}: {exc}") + continue + digest = hashlib.sha256(data).hexdigest() + if payload.get("sha256") and payload["sha256"] != digest: + errors.append(f"{label}: the image changed while it was being read; try again.") + continue + if digest in seen: + errors.append(f"{label}: the same image is in this draft twice.") + continue + seen.add(digest) + width, height = int(payload["width"]), int(payload["height"]) + errors.extend(_image_problems(label, data, str(payload["mime_type"]), width, height)) + images.append({**payload, "sha256": digest, "size_bytes": len(data), + "base64_chars": 4 * ((len(data) + 2) // 3)}) + return images, errors + + +def _approved_image(payload: dict) -> bytes: + """The previewed bytes of an image, re-read now; refuses one that changed or no longer fits.""" + from adloop.ads.write import load_image_bytes + + label = _image_label(payload) + data, _name = load_image_bytes(payload) + if hashlib.sha256(data).hexdigest() != payload["sha256"]: + raise ValueError(f"{label} changed since the preview; draft again.") + problems = _image_problems(label, data, str(payload["mime_type"]), int(payload["width"]), int(payload["height"])) + if problems: + raise ValueError("; ".join(problems)) + return data + + +def _describe_ms_image(payload: dict) -> str: + width, height = int(payload["width"]), int(payload["height"]) + return (f"{_image_label(payload)}: {_IMAGE_FORMATS.get(str(payload['mime_type']), payload['mime_type'])} " + f"{width}x{height} ({width / height:.2f}:1), {payload['size_bytes'] / 1024:.1f} KB") + + +def _linked_images(config, account, customer, association: str, entity_id: str) -> list[dict]: + return [a["AdExtension"] for a in _associated_extensions(config, account, customer, association, entity_id) + if a["AdExtension"].get("Type") == "ImageAdExtension"] + + +def draft_microsoft_image_extension( + config: AdLoopConfig, + *, + ad_account_id: str = "", + campaign_id: str = "", + ad_group_id: str = "", + scope: str = "", + image_paths: list[str] | None = None, + image_urls: list[str] | None = None, + upload_ids: list[str] | None = None, + alt_text: str = "", + display_text: str = "", + final_url: str = "", +) -> dict: + """Draft image extensions (one per image) for a campaign, an ad group or the account. + + Every image is loaded and checked now against Microsoft's limits; the + plan keeps its sha256, and the dry run and the apply read it again and + refuse one that changed. The apply uploads the images to the account's + media library (Media/Add), creates one ImageAdExtension per image and + links them (AdExtensionsAssociations/Set). + """ + from adloop.runtime import deployment_mode + + operation = "microsoft_add_image_extension" + blocked = _guard(operation, config) + if blocked: + return blocked + paths, urls, uploads = _clean(image_paths), _clean(image_urls), _clean(upload_ids) + if paths and deployment_mode() == "server": + return {"error": "image_paths can't be used here: local file paths aren't available on a hosted server; " + "pass image_urls or upload_ids instead."} + alt, display, url = (alt_text or "").strip(), (display_text or "").strip(), (final_url or "").strip() + errors: list[str] = [] + warnings: list[str] = [] + if not alt: + errors.append("alt_text is required: it describes the image for screen readers and shows on hover " + f"(at most {_ALT_TEXT_MAX} characters).") + elif len(alt) > _ALT_TEXT_MAX: + errors.append(f"alt_text is {len(alt)} characters; Microsoft allows {_ALT_TEXT_MAX}.") + if len(display) > _DISPLAY_TEXT_MAX: + errors.append(f"display_text is {len(display)} characters; Microsoft allows {_DISPLAY_TEXT_MAX}.") + count = len(paths) + len(urls) + len(uploads) + if not count: + errors.append("At least one image (image_paths, image_urls or upload_ids) is required.") + elif count > _IMAGES_PER_DRAFT: + errors.append(f"At most {_IMAGES_PER_DRAFT} images per draft (Microsoft uploads 10 per request); got {count}.") + if url: + _check_url(url, errors, warnings) + if errors: + return _validation_error(errors) + images, image_errors = _draft_images(paths, urls, uploads) + if image_errors: + return _validation_error(image_errors) + + _meta, account, customer = _ctx(config, ad_account_id) + target = _extension_target(config, account, customer, str(campaign_id or ""), (scope or "").strip().lower(), + ad_group_id=str(ad_group_id or "").strip()) + if isinstance(target, dict): + return target + association, entity_id, where = target + existing = _linked_images(config, account, customer, association, entity_id) + total = len(existing) + len(images) + if total > _IMAGE_LINKS_MAX: + return _validation_error([( + f"{where} has {len(existing)} image extension(s); {len(images)} more would make {total}, over " + f"Microsoft's {_IMAGE_LINKS_MAX} per account, campaign or ad group. Unlink some first " + "(remove_microsoft_entity, entity_type extension_association).")]) + if total > _IMAGE_LINKS_LOW: + warnings.append(f"{where} would have {total} image extensions. Microsoft's image extension reference " + f"lists {_IMAGE_LINKS_LOW} per entity while its help and bulk pages say " + f"{_IMAGE_LINKS_MAX}; if Microsoft refuses the link, the extensions stay in the " + "library unlinked.") + layouts = ["SearchSingle"] + (["SearchMultiple"] if display else []) + # [AUD]: "you can also extend search into native via image ad extensions". + warnings.append("Image extensions can take these search ads beyond Bing results: Microsoft's audience ads " + "guide says search ads are extended to native placements on the Microsoft Audience Network " + "(Outlook, MSN) using their image extensions. Check the ad groups' Audience Network setting " + "(get_microsoft_ad_groups) if they should stay on search.") + if display: + # [HELP]: at least five images and four image extensions; not with + # sitelink, enhanced sitelink, dynamic product, dynamic data or price cards. + warnings.append("display_text makes them eligible for the multi-image layout too. Microsoft shows that " + "layout only with at least five images across at least four image extensions, and not " + "next to sitelink, price, dynamic product or dynamic data extension cards.") + if any(p["mime_type"] == "image/png" for p in images): + warnings.append("Microsoft converts PNG images to JPEG; upload a JPEG if the quality matters.") + if existing: + warnings.append(f"{where} already has {len(existing)} image extension(s); Microsoft rotates them.") + shown: dict[str, Any] = {"images": [_describe_ms_image(p) for p in images], "alt_text": alt} + if display: + shown["display_text"] = display + shown["final_url"] = url or "the ad's own final URL" + shown["layouts"] = layouts + return _plan( + operation, _ASSOCIATION_ENTITY[association], entity_id, account, + _base_changes(account, customer, entity_name=where, association_type=association, entity_id=entity_id, + **shown, image_payloads=images), + warnings=warnings, + ) + + +def _image_extension(c: dict, media_id: str, payload: dict) -> dict: + """The ImageAdExtension for one uploaded image [EXT]; the image is its 1.91:1 LandscapeImageMedia asset.""" + ext: dict[str, Any] = { + "Type": "ImageAdExtension", + "AlternativeText": c["alt_text"], + "Description": str(payload.get("name") or "")[:_DESCRIPTION_MAX] or None, + "ImageMediaIds": [int(media_id)], + "Images": [{"Asset": {"Type": "ImageAsset", "Id": int(media_id), "SubType": "LandscapeImageMedia"}}], + "Layouts": list(c["layouts"]), + } + if c.get("display_text"): + ext["DisplayText"] = c["display_text"] + if c["final_url"].startswith(("http://", "https://")): + ext["FinalUrls"] = [c["final_url"]] + return {k: v for k, v in ext.items() if v is not None} + + +def _extension_row(assoc: dict, association: str, label: str, campaign_name: str | None) -> dict: + ext = assoc["AdExtension"] + kind = str(ext.get("Type") or "") + entity_id = str(assoc["EntityId"]) + row: dict[str, Any] = { + "level": _ASSOCIATION_ENTITY.get(association, association.lower()), "entity": label, "entity_id": entity_id, + "type": kind.replace("AdExtension", ""), "extension_id": str(ext.get("Id")), + "content": ext.get("Text") or ext.get("DisplayText") or ext.get("PhoneNumber") + or (f"{ext.get('Header')}: {', '.join(ext.get('Values') or [])}" if ext.get("Header") else None), + "final_urls": ext.get("FinalUrls"), + "editorial_status": assoc.get("EditorialStatus"), + "remove_id": f"{ext.get('Id')}~{entity_id}~{association}", + } + if association == "AdGroup": + row["campaign"] = campaign_name + if kind == "ImageAdExtension": + row.update(content=ext.get("AlternativeText"), alt_text=ext.get("AlternativeText"), + display_text=ext.get("DisplayText"), media_ids=_image_media_ids(ext), layouts=ext.get("Layouts"), + label=ext.get("Description"), source=ext.get("SourceType")) + return row + + +def _image_media_ids(ext: dict) -> list[str]: + """The media an image extension shows: its ImageMediaIds, or the assets of its Images links.""" + media = [str(i) for i in ext.get("ImageMediaIds") or [] if i is not None] or [ + str(link["Asset"]["Id"]) for link in ext.get("Images") or [] + if isinstance(link, dict) and isinstance(link.get("Asset"), dict) and link["Asset"].get("Id") is not None] + return sorted(set(media), key=lambda m: (len(m), m)) + + +# The association query returns image extensions without their Images, +# DisplayText and Layouts; those come only from GetAdExtensionsByIds when +# ReturnAdditionalFields asks for them (an unknown field name fails the whole +# request). Media metadata then gives each image's size and a viewable URL. +_IMAGE_EXTRA_FIELDS = "Images,DisplayText,Layouts" + + +def _image_details(config: AdLoopConfig, account: str, customer: str, rows: list[dict]) -> list[str]: + """Fill image rows with their media, display text, layouts and image links; insights on failure.""" + image_rows = [r for r in rows if r["type"] == "Image"] + if not image_rows: + return [] + try: + extensions: dict[str, dict] = {} + for chunk in _chunks(sorted({r["extension_id"] for r in image_rows})): + payload = campaign_request( + config, "AdExtensions/QueryByIds", + {"AccountId": account, "AdExtensionIds": [int(i) for i in chunk], + "AdExtensionType": "ImageAdExtension", "ReturnAdditionalFields": _IMAGE_EXTRA_FIELDS}, + account_id=account, customer_id=customer, + ) + extensions.update({str(e.get("Id")): e for e in payload.get("AdExtensions") or [] if isinstance(e, dict)}) + for row in image_rows: + ext = extensions.get(row["extension_id"]) + if ext: + row.update(media_ids=_image_media_ids(ext) or row["media_ids"], + display_text=ext.get("DisplayText") or row["display_text"], + layouts=ext.get("Layouts") or row["layouts"]) + media: dict[str, dict] = {} + for chunk in _chunks(sorted({m for r in image_rows for m in r["media_ids"]})): + payload = campaign_request(config, "MediaMetaData/QueryByIds", + {"AccountId": account, "MediaIds": [int(m) for m in chunk]}, + account_id=account, customer_id=customer) + for item in payload.get("MediaMetaData") or []: + if not isinstance(item, dict): + continue + reps = [r for r in item.get("Representations") or [] if isinstance(r, dict)] + best = max(reps, key=lambda r: (r.get("Width") or 0) * (r.get("Height") or 0), default={}) + media[str(item.get("Id"))] = {"media_id": str(item.get("Id")), "media_type": item.get("MediaType"), + "width": best.get("Width"), "height": best.get("Height"), + "url": best.get("Url")} + except MicrosoftAdsApiError as exc: + return [f"Image details could not be read, so image rows lack their images and display text: {exc}"] + for row in image_rows: + row["images"] = [media.get(m) or {"media_id": m} for m in row["media_ids"]] + return [] + + +def get_microsoft_ad_extensions(config: AdLoopConfig, *, ad_account_id: str = "", campaign_id: str = "") -> dict: + """Sitelinks, callouts, snippets, call and image extensions on ad groups, campaigns and the account.""" + meta, account, customer = _ctx(config, ad_account_id) + campaigns = [c for c in _campaigns(config, account, customer) if not campaign_id or str(c.get("Id")) == str(campaign_id)] + rows = [] + targets = [("Campaign", str(c.get("Id")), c.get("Name")) for c in campaigns] + if not campaign_id: + targets.append(("Account", account, "account")) + for association, entity_id, label in targets: + for a in _associated_extensions(config, account, customer, association, entity_id): + rows.append(_extension_row(a, association, label, None)) + # Ad group links (image extensions often live there), up to 100 ad groups a request. + groups = {str(g.get("Id")): (g, c) for c in campaigns for g in _ad_groups(config, account, customer, str(c.get("Id"))) + if g.get("Status") != "Deleted"} + for chunk in _chunks(list(groups)): + for a in _associated_extensions(config, account, customer, "AdGroup", chunk): + group, campaign = groups.get(a["EntityId"], ({}, {})) + rows.append(_extension_row(a, "AdGroup", group.get("Name") or a["EntityId"], campaign.get("Name"))) + insights = _image_details(config, account, customer, rows) + for c in campaigns: + mine = [r for r in rows if r["level"] == "campaign" and r["entity_id"] == str(c.get("Id"))] + if not any(r["type"] == "Sitelink" for r in mine): + insights.append(f"Campaign '{c.get('Name')}' has no sitelinks of its own.") + rejected = [r for r in rows if r["editorial_status"] in ("Disapproved", "Inactive")] + if rejected: + insights.append(f"{len(rejected)} extension(s) are disapproved or inactive.") + if not any(r["type"] == "Image" for r in rows): + insights.append("No image extensions are linked. Microsoft may add autogenerated ones to ad groups " + "without any; draft_microsoft_image_extension adds your own.") + return {"ad_account_id": account, "extensions": rows, "total": len(rows), "insights": insights} + + +# --------------------------------------------------------------------------- +# Removal +# --------------------------------------------------------------------------- + +REMOVABLE = ("campaign", "ad_group", "ad", "keyword", "negative_keyword", "negative_list_item", + "campaign_criterion", "extension_association") + + +def remove_microsoft_entity(config: AdLoopConfig, *, ad_account_id: str = "", entity_type: str = "", entity_id: str = "") -> dict: + """Draft deleting an entity (irreversible; double confirmation).""" + operation = "microsoft_remove_entity" + blocked = _guard(operation, config) + if blocked: + return blocked + entity_type = (entity_type or "").strip().lower() + entity_id = str(entity_id or "").strip() + if entity_type not in REMOVABLE: + return _validation_error([f"entity_type must be one of {list(REMOVABLE)}."]) + if not entity_id: + return _validation_error(["entity_id is required."]) + meta, account, customer = _ctx(config, ad_account_id) + shown: dict[str, Any] = {} + request: dict[str, Any] + if entity_type in ("campaign", "ad_group", "ad", "keyword"): + found = find_entity(config, account, customer, entity_type, entity_id) + if not found: + return {"error": f"Microsoft {entity_type.replace('_', ' ')} '{entity_id}' was not found."} + entity = found["entity"] + label = entity.get("Name") or entity.get("Text") or f"{entity.get('Type')} ad {entity_id}" + shown = {"name": label, "campaign": found["campaign"].get("Name"), + "ad_group": (found.get("ad_group") or {}).get("Name"), "current_status": entity.get("Status")} + if entity_type == "campaign": + request = {"path": "Campaigns", "body": {"AccountId": account, "CampaignIds": [entity_id]}} + elif entity_type == "ad_group": + request = {"path": "AdGroups", "body": {"CampaignId": str(found["campaign"].get("Id")), "AdGroupIds": [entity_id]}} + elif entity_type == "ad": + request = {"path": "Ads", "body": {"AdGroupId": str(found["ad_group"].get("Id")), "AdIds": [entity_id]}} + else: + request = {"path": "Keywords", "body": {"AdGroupId": str(found["ad_group"].get("Id")), "KeywordIds": [entity_id]}} + else: + parts = entity_id.split("~") + if entity_type == "negative_keyword" and len(parts) == 3 and parts[0] in ("Campaign", "AdGroup"): + kind, owner, neg = parts + request = {"path": "EntityNegativeKeywords", "body": {"EntityNegativeKeywords": [ + {"EntityId": int(owner), "EntityType": kind, "NegativeKeywords": [{"Id": int(neg)}]}]}} + shown = {"negative_keyword_id": neg, "on": f"{kind} {owner}"} + elif entity_type == "negative_list_item" and len(parts) == 2: + list_id, item = parts + request = {"path": "ListItems", "body": {"ListItemIds": [int(item)], "SharedList": {"Type": _LIST_TYPE, "Id": int(list_id)}, + "SharedEntityScope": "Account"}} + shown = {"list_id": list_id, "item_id": item} + elif entity_type == "campaign_criterion" and len(parts) == 2: + cid, crit = parts + request = {"path": "CampaignCriterions", "body": {"CampaignCriterionIds": [int(crit)], "CampaignId": int(cid), + "CriterionType": "Targets"}} + shown = {"campaign_id": cid, "criterion_id": crit} + elif entity_type == "extension_association" and len(parts) == 3 and parts[2] in _ASSOCIATION_ENTITY: + ext, owner, association = parts + request = {"path": "AdExtensionsAssociations", "body": {"AccountId": account, "AssociationType": association, + "AdExtensionIdToEntityIdAssociations": [ + {"AdExtensionId": int(ext), "EntityId": int(owner)}]}} + shown = {"extension_id": ext, "removed_from": f"{association} {owner}"} + else: + return _validation_error([ + "entity_id format: negative_keyword 'Campaign~~' or 'AdGroup~~', " + "negative_list_item '~', campaign_criterion '~', " + "extension_association '~~' (the remove_id values the read " + "tools return)." + ]) + warnings = ["Deleting cannot be undone; pausing keeps the history and lets it come back."] if entity_type in ( + "campaign", "ad_group", "ad", "keyword") else [] + if entity_type == "extension_association": + warnings.append("This unlinks the extension only; the extension (and an image extension's images) " + "stays in the account's library.") + return _plan(operation, entity_type, entity_id, account, + _base_changes(account, customer, entity_name=shown.get("name") or entity_id, target=shown, request=request), + warnings=warnings, double=True) + + +# --------------------------------------------------------------------------- +# Dry run and apply +# --------------------------------------------------------------------------- + +OPERATIONS = { + "microsoft_update_campaign", "microsoft_update_targeting", "microsoft_create_campaign", + "microsoft_create_ad_group", "microsoft_update_ad_group", "microsoft_add_keywords", + "microsoft_update_keyword_bids", "microsoft_add_negative_keywords", "microsoft_create_negative_list", + "microsoft_add_to_negative_list", "microsoft_attach_negative_list", "microsoft_detach_negative_list", + "microsoft_create_rsa", "microsoft_update_rsa", "microsoft_add_sitelinks", "microsoft_add_callouts", + "microsoft_add_structured_snippet", "microsoft_add_call_extension", "microsoft_add_image_extension", + "microsoft_remove_entity", +} + + +def _require_unchanged(entity: dict, before: dict, what: str) -> None: + for key, value in (before or {}).items(): + if not _same(entity.get(key), value): + raise ValueError(f"The {what}'s {key} changed since the draft; draft again.") + + +def preflight(config: AdLoopConfig, plan: ChangePlan) -> dict: + """Re-read what the plan touches and re-check the gates; sends nothing.""" + from adloop.safety.guards import check_budget_cap + + c = plan.changes or {} + account, customer = c["ad_account_id"], c.get("customer_id", "") + op = plan.operation + checks: dict[str, Any] = {"ad_account_id": account} + + def entity(kind: str, eid: str) -> dict: + found = find_entity(config, account, customer, kind, eid) + if not found: + raise ValueError(f"{kind.replace('_', ' ')} '{eid}' no longer exists.") + return found + + if op == "microsoft_update_campaign": + campaign = entity("campaign", plan.entity_id)["entity"] + _require_unchanged(campaign, c["before"], "campaign") + scheme = c["update"].get("BiddingScheme") + if scheme: + _check_bid((((campaign.get("BiddingScheme") or {}).get("MaxCpc")) or {}).get("Amount"), + (scheme.get("MaxCpc") or {}).get("Amount"), config) + if scheme.get("Type") in _MANUAL and _active_broad_keywords(config, account, customer, plan.entity_id): + raise ValueError("The campaign now has active broad-match keywords; manual bidding with broad match " + "wastes spend. Change them to phrase or exact first.") + elif op == "microsoft_update_targeting": + ops = c.get("operations") or {} + scheduled = {str(s.get("criterion_id")) for s in (c["before"].get("schedule") or [])} + if (any(((x.get("Criterion") or {}).get("Type")) == "DayTimeCriterion" for x in ops.get("add") or []) + or any(str(i) in scheduled for i in ops.get("delete") or [])): + raise ValueError("This plan changes the ad schedule and was drafted by an earlier AdLoop version, " + "which did not check the schedule's time zone mode or order the windows Microsoft " + "allows; draft it again.") + campaign = entity("campaign", plan.entity_id)["entity"] + now = _current_targeting(config, account, customer, plan.entity_id) + if "searcher_time_zone" in c["before"]: + now["searcher_time_zone"] = bool(campaign.get("AdScheduleUseSearcherTimeZone")) + if now["searcher_time_zone"] != c["before"]["searcher_time_zone"]: + raise ValueError("The campaign's ad schedule time zone setting (AdScheduleUseSearcherTimeZone) " + "changed since the draft, so the approved hours would mean other times; draft again.") + if not _same(now, c["before"]): + raise ValueError("The campaign's targeting changed since the draft; draft again.") + elif op == "microsoft_create_campaign": + check_budget_cap(float(c["daily_budget"]), config.safety) + if c["entity_name"].lower() in {str(x.get("Name")).lower() for x in _campaigns(config, account, customer)}: + raise ValueError(f"A campaign named '{c['entity_name']}' now exists (an earlier attempt may have created it).") + checks["budget_cap_ok"] = True + elif op == "microsoft_create_ad_group": + campaign = entity("campaign", c["campaign_id"])["entity"] + if c["entity_name"].lower() in {str(g.get("Name")).lower() for g in _ad_groups(config, account, customer, c["campaign_id"])}: + raise ValueError(f"An ad group named '{c['entity_name']}' now exists in the campaign.") + errors = [] + _refuse_broad_on_manual(c["keyword_rows"], campaign, errors) + if _strategy_name(campaign.get("BiddingScheme")) in _MANUAL and not c["ad_group"].get("CpcBid"): + errors.append("The campaign now uses manual bidding, which needs a default bid for the ad group.") + if errors: + raise ValueError("; ".join(errors)) + elif op == "microsoft_update_ad_group": + group = entity("ad_group", plan.entity_id)["entity"] + _require_unchanged(group, c["before"], "ad group") + if "CpcBid" in c["update"]: + _check_bid(_money(group.get("CpcBid")), c["update"]["CpcBid"]["Amount"], config) + elif op == "microsoft_add_keywords": + found = entity("ad_group", plan.entity_id) + errors = [] + _refuse_broad_on_manual(c["keyword_rows"], found["campaign"], errors) + if errors: + raise ValueError("; ".join(errors)) + have = {(str(k.get("Text")).lower(), k.get("MatchType")) for k in _keywords(config, account, customer, plan.entity_id) + if k.get("Status") != "Deleted"} + again = [r["Text"] for r in c["keyword_rows"] if (r["Text"].lower(), r["MatchType"]) in have] + if again: + raise ValueError(f"Keyword(s) {again} are in the ad group now (an earlier attempt may have added them).") + elif op == "microsoft_update_keyword_bids": + group = entity("ad_group", plan.entity_id)["entity"] + if not _same(group.get("CpcBid"), c.get("default_bid_before")): + raise ValueError("The ad group's default bid changed since the draft; draft again.") + now = {str(k.get("Id")): k.get("Bid") for k in _keywords(config, account, customer, plan.entity_id)} + for kid, bid in (c["before"] or {}).items(): + if kid not in now: + raise ValueError(f"Keyword {kid} no longer exists.") + if not _same(now[kid], bid): + raise ValueError(f"Keyword {kid}'s bid changed since the draft; draft again.") + default = _money(group.get("CpcBid")) + for row in c["keyword_rows"]: + current = _money(now[str(row["Id"])]) or default + proposed = row["Bid"]["Amount"] if row["Bid"]["Amount"] is not None else default + _check_bid(current, proposed, config) + elif op == "microsoft_add_negative_keywords": + found = entity(plan.entity_type, plan.entity_id) + have = {(str(n.get("Text")).lower(), n.get("MatchType")) for n in _entity_negatives( + config, account, customer, c["entity_kind"], plan.entity_id, + "" if plan.entity_type == "campaign" else str(found["campaign"].get("Id")))} + again = [r["Text"] for r in c["negative_rows"] if (r["Text"].lower(), r["MatchType"]) in have] + if again: + raise ValueError(f"Negative(s) {again} are there now (an earlier attempt may have added them).") + elif op == "microsoft_create_negative_list": + if c["entity_name"].lower() in {str(x.get("Name")).lower() for x in _shared_lists(config, account, customer)}: + raise ValueError(f"A list named '{c['entity_name']}' now exists (an earlier attempt may have created it).") + elif op in ("microsoft_add_to_negative_list", "microsoft_attach_negative_list", "microsoft_detach_negative_list"): + if plan.entity_id not in {str(x.get("Id")) for x in _shared_lists(config, account, customer)}: + raise ValueError(f"Negative keyword list {plan.entity_id} no longer exists.") + if op == "microsoft_add_to_negative_list": + have = {(str(i.get("Text")).lower(), i.get("MatchType")) for i in _list_items(config, account, customer, plan.entity_id)} + again = [r["Text"] for r in c["negative_rows"] if (r["Text"].lower(), r["MatchType"]) in have] + if again: + raise ValueError(f"Negative(s) {again} are in the list now (an earlier attempt may have added them).") + elif op == "microsoft_create_rsa": + found = entity("ad_group", plan.entity_id) + errors: list[str] = [] + _check_url(c["final_url"], errors, []) + if errors: + raise ValueError("; ".join(errors)) + wanted = sorted(l["Asset"]["Text"] for l in c["ad"]["Headlines"]) + for ad in _ads(config, account, customer, plan.entity_id): + if sorted(str(l.get("Asset", {}).get("Text")) for l in ad.get("Headlines") or []) == wanted: + raise ValueError(f"Ad group '{found['entity'].get('Name')}' already has an RSA with these headlines (ad {ad.get('Id')}).") + elif op == "microsoft_update_rsa": + found = entity("ad", plan.entity_id) + _require_unchanged(found["entity"], c["before"], "ad") + if c["update"].get("FinalUrls"): + errors = [] + _check_url(c["update"]["FinalUrls"][0], errors, []) + if errors: + raise ValueError("; ".join(errors)) + elif op in ("microsoft_add_sitelinks", "microsoft_add_callouts", "microsoft_add_structured_snippet", + "microsoft_add_call_extension"): + if c["association_type"] == "Campaign": + entity("campaign", c["entity_id"]) + linked = _associated_extensions(config, account, customer, c["association_type"], c["entity_id"]) + if op == "microsoft_add_call_extension" and any(a["AdExtension"].get("Type") == "CallAdExtension" for a in linked): + raise ValueError("The campaign got a call extension since the draft.") + def key(ext): # noqa: E306 + return json.dumps({k: ext.get(k) for k in ("Type", "Text", "DisplayText", "Header", "Values", "PhoneNumber")}, + sort_keys=True).lower() + now = {key(a["AdExtension"]) for a in linked} + again = [e for e in c["extensions"] if key(e) in now] + if again: + raise ValueError(f"{len(again)} of these extensions are linked now (an earlier attempt may have added them).") + if op == "microsoft_add_sitelinks": + errors = [] + for ext in c["extensions"]: + _check_url(ext["FinalUrls"][0], errors, []) + if errors: + raise ValueError("; ".join(errors)) + elif op == "microsoft_add_image_extension": + if c["association_type"] in ("Campaign", "AdGroup"): + entity(_ASSOCIATION_ENTITY[c["association_type"]], c["entity_id"]) + images = c["image_payloads"] + for payload in images: + _approved_image(payload) # re-reads (URLs re-fetched) and re-checks every image + linked = _linked_images(config, account, customer, c["association_type"], c["entity_id"]) + if len(linked) + len(images) > _IMAGE_LINKS_MAX: + raise ValueError(f"{c['entity_name']} now has {len(linked)} image extension(s); {len(images)} more would " + f"go over Microsoft's {_IMAGE_LINKS_MAX}.") + if c["final_url"].startswith(("http://", "https://")): + errors = [] + _check_url(c["final_url"], errors, []) + if errors: + raise ValueError("; ".join(errors)) + checks["images_verified"] = len(images) + elif op == "microsoft_remove_entity": + if plan.entity_type in ("campaign", "ad_group", "ad", "keyword"): + entity(plan.entity_type, plan.entity_id) + else: + raise ValueError(f"Unknown Microsoft operation: {op}") + checks["checked"] = op.replace("microsoft_", "") + return checks + + +def apply_plan(config: AdLoopConfig, plan: ChangePlan) -> dict: + """Execute a management plan (after :func:`preflight`, which the caller runs first).""" + c = plan.changes or {} + account = c["ad_account_id"] + op = plan.operation + progress = _Progress() + + if op == "microsoft_update_campaign": + _call(config, c, "PUT", "Campaigns", {"AccountId": account, "Campaigns": [c["update"]]}, "campaign update") + return {"campaign_id": plan.entity_id, "updated": sorted(k for k in c["update"] if k != "Id")} + + if op == "microsoft_update_targeting": + ops = c["operations"] + for chunk in _chunks(ops["add"]): + progress.step("Adding targeting", lambda chunk=chunk: _call( + config, c, "POST", "CampaignCriterions", {"CampaignCriterions": chunk, "CriterionType": "Targets"}, "targeting additions")) + progress.done.append(f"added {len(chunk)} criterion(s)") + for chunk in _chunks(ops["update"]): + progress.step("Updating location intent", lambda chunk=chunk: _call( + config, c, "PUT", "CampaignCriterions", {"CampaignCriterions": chunk, "CriterionType": "Targets"}, "location intent")) + progress.done.append("updated location intent") + for chunk in _chunks(ops["delete"]): + progress.step("Removing old targeting", lambda chunk=chunk: _call( + config, c, "DELETE", "CampaignCriterions", + {"CampaignCriterionIds": [int(x) for x in chunk], "CampaignId": int(plan.entity_id), "CriterionType": "Targets"}, + "targeting removal")) + progress.done.append(f"removed {len(chunk)} criterion(s)") + # Schedule windows: non-overlapping new ones, then the old ones out, + # then the rest (see _schedule_steps). + for chunk in _chunks(ops.get("schedule_add_first") or []): + progress.step("Adding new ad schedule windows", lambda chunk=chunk: _call( + config, c, "POST", "CampaignCriterions", {"CampaignCriterions": chunk, "CriterionType": "Targets"}, "ad schedule")) + progress.done.append(f"added {len(chunk)} schedule window(s)") + for chunk in _chunks(ops.get("schedule_delete") or []): + progress.step("Removing the old ad schedule windows", lambda chunk=chunk: _call( + config, c, "DELETE", "CampaignCriterions", + {"CampaignCriterionIds": [int(x) for x in chunk], "CampaignId": int(plan.entity_id), "CriterionType": "Targets"}, + "ad schedule removal")) + progress.done.append(f"removed {len(chunk)} schedule window(s)") + remaining = list(ops.get("schedule_kept") or []) + if ops.get("schedule_add_first"): + remaining.append(f"{len(ops['schedule_add_first'])} new window(s) added before the removal") + for chunk in _chunks(ops.get("schedule_add_after") or []): + progress.step( + "Adding the new ad schedule windows (the windows they replace are already removed; until this " + "succeeds the campaign keeps " + + (", ".join(remaining) if remaining else "no ad schedule and serves at all hours") + ")", + lambda chunk=chunk: _call(config, c, "POST", "CampaignCriterions", + {"CampaignCriterions": chunk, "CriterionType": "Targets"}, "ad schedule")) + progress.done.append(f"added {len(chunk)} schedule window(s)") + schedule_added = len(ops.get("schedule_add_first") or []) + len(ops.get("schedule_add_after") or []) + return {"campaign_id": plan.entity_id, "added": len(ops["add"]) + schedule_added, "updated": len(ops["update"]), + "removed": len(ops["delete"]) + len(ops.get("schedule_delete") or [])} + + if op == "microsoft_create_campaign": + payload = _call(config, c, "POST", "Campaigns", {"AccountId": account, "Campaigns": [c["campaign"]]}, "new campaign") + campaign_id = str((payload.get("CampaignIds") or [None])[0]) + progress.done.append(f"created campaign {campaign_id} (paused)") + criteria = [{**x, "CampaignId": campaign_id} for x in c["criteria"]] + for chunk in _chunks(criteria): + progress.step("Adding the campaign's locations", lambda chunk=chunk: _call( + config, c, "POST", "CampaignCriterions", {"CampaignCriterions": chunk, "CriterionType": "Targets"}, "locations")) + return {"campaign_id": campaign_id, "name": c["entity_name"], "status": "Paused", + "next": "Add ad groups, keywords, ads and extensions, then enable it."} + + if op == "microsoft_create_ad_group": + payload = _call(config, c, "POST", "AdGroups", {"CampaignId": c["campaign_id"], "AdGroups": [c["ad_group"]]}, "new ad group") + ad_group_id = str((payload.get("AdGroupIds") or [None])[0]) + progress.done.append(f"created ad group {ad_group_id}") + for chunk in _chunks(c["keyword_rows"], 1000): + progress.step("Adding its keywords", lambda chunk=chunk: _call( + config, c, "POST", "Keywords", {"AdGroupId": ad_group_id, "Keywords": chunk}, "keywords")) + return {"ad_group_id": ad_group_id, "name": c["entity_name"], "keywords_added": len(c["keyword_rows"])} + + if op == "microsoft_update_ad_group": + _call(config, c, "PUT", "AdGroups", {"CampaignId": c["campaign_id"], "AdGroups": [c["update"]], + "UpdateAudienceAdsBidAdjustment": bool(c.get("update_audience_adjustment"))}, + "ad group update") + return {"ad_group_id": plan.entity_id, "updated": sorted(k for k in c["update"] if k != "Id")} + + if op == "microsoft_add_keywords": + payload = _call(config, c, "POST", "Keywords", {"AdGroupId": plan.entity_id, "Keywords": c["keyword_rows"]}, "keywords") + return {"ad_group_id": plan.entity_id, "keyword_ids": [str(i) for i in payload.get("KeywordIds") or []]} + + if op == "microsoft_update_keyword_bids": + _call(config, c, "PUT", "Keywords", {"AdGroupId": plan.entity_id, "Keywords": c["keyword_rows"]}, "keyword bids") + return {"ad_group_id": plan.entity_id, "keywords_updated": len(c["keyword_rows"])} + + if op == "microsoft_add_negative_keywords": + _call(config, c, "POST", "EntityNegativeKeywords", {"EntityNegativeKeywords": [ + {"EntityId": int(plan.entity_id), "EntityType": c["entity_kind"], "NegativeKeywords": c["negative_rows"]}]}, + "negative keywords") + return {"entity": c["entity_name"], "negatives_added": len(c["negative_rows"])} + + if op == "microsoft_create_negative_list": + items = [{"Type": "NegativeKeyword", **r} for r in c["negative_rows"]] + payload = _call(config, c, "POST", "SharedEntity", {"SharedEntity": {"Type": _LIST_TYPE, "Name": c["entity_name"]}, + "ListItems": items[:5000], "SharedEntityScope": "Account"}, + "negative keyword list") + list_id = str(payload.get("SharedEntityId")) + progress.done.append(f"created list {list_id} with {len(items)} negatives") + if c["campaign_ids"]: + progress.step("Attaching the list", lambda: _call(config, c, "POST", "SharedEntityAssociations/Set", { + "Associations": [{"EntityId": int(cid), "EntityType": "Campaign", "SharedEntityId": int(list_id), + "SharedEntityType": _LIST_TYPE} for cid in c["campaign_ids"]], + "SharedEntityScope": "Account"}, "list attachment")) + return {"list_id": list_id, "name": c["entity_name"], "negatives": len(items), "attached_to": c["attach_to"]} + + if op == "microsoft_add_to_negative_list": + items = [{"Type": "NegativeKeyword", **r} for r in c["negative_rows"]] + for chunk in _chunks(items, 5000): + progress.step("Adding to the list", lambda chunk=chunk: _call(config, c, "POST", "ListItems", { + "ListItems": chunk, "SharedList": {"Type": _LIST_TYPE, "Id": int(plan.entity_id)}, + "SharedEntityScope": "Account"}, "list items")) + return {"list_id": plan.entity_id, "negatives_added": len(items)} + + if op in ("microsoft_attach_negative_list", "microsoft_detach_negative_list"): + body = {"Associations": [{"EntityId": int(cid), "EntityType": "Campaign", "SharedEntityId": int(plan.entity_id), + "SharedEntityType": _LIST_TYPE} for cid in c["campaign_ids"]], + "SharedEntityScope": "Account"} + if op == "microsoft_attach_negative_list": + _call(config, c, "POST", "SharedEntityAssociations/Set", body, "list attachment") + else: + _call(config, c, "DELETE", "SharedEntityAssociations", body, "list detachment") + return {"list_id": plan.entity_id, "campaigns": c["campaigns"]} + + if op == "microsoft_create_rsa": + payload = _call(config, c, "POST", "Ads", {"AdGroupId": plan.entity_id, "Ads": [c["ad"]]}, "responsive search ad") + return {"ad_id": str((payload.get("AdIds") or [None])[0]), "status": "Paused", + "next": "Enable it with enable_microsoft_entity once reviewed."} + + if op == "microsoft_update_rsa": + _call(config, c, "PUT", "Ads", {"AdGroupId": c["ad_group_id"], "Ads": [c["update"]]}, "responsive search ad update") + return {"ad_id": plan.entity_id, "updated": sorted(k for k in c["update"] if k not in ("Id", "Type"))} + + if op in ("microsoft_add_sitelinks", "microsoft_add_callouts", "microsoft_add_structured_snippet", + "microsoft_add_call_extension"): + payload = _call(config, c, "POST", "AdExtensions", {"AccountId": account, "AdExtensions": c["extensions"]}, "extensions") + ids = [str((i or {}).get("Id")) for i in payload.get("AdExtensionIdentities") or [] if i] + progress.done.append(f"created extension(s) {ids}") + progress.step("Linking the extensions", lambda: _call(config, c, "POST", "AdExtensionsAssociations/Set", { + "AccountId": account, "AssociationType": c["association_type"], + "AdExtensionIdToEntityIdAssociations": [{"AdExtensionId": int(i), "EntityId": int(c["entity_id"])} for i in ids], + }, "extension links")) + return {"extension_ids": ids, "linked_to": c["entity_name"]} + + if op == "microsoft_add_image_extension": + return _apply_image_extensions(config, c, progress) + + if op == "microsoft_remove_entity": + request = c["request"] + _call(config, c, "DELETE", request["path"], request["body"], f"{plan.entity_type.replace('_', ' ')} removal") + return {"removed": plan.entity_type, "entity_id": plan.entity_id} + + raise ValueError(f"Unknown Microsoft operation: {op}") + + +def _apply_image_extensions(config: AdLoopConfig, c: dict, progress: _Progress) -> dict: + """Media/Add, then one ImageAdExtension per image, then the links; a later failure names what exists.""" + from adloop.safety.outcomes import PartialApplyError + + account = c["ad_account_id"] + payloads = c["image_payloads"] + # Every image is read and checked before anything is sent. + data = [_approved_image(p) for p in payloads] + # REST v13 AddMedia is POST .../CampaignManagement/v13/Media [ADD]; GenericImage + # is the MediaType Microsoft recommends for image extension media [IMG]. + media = [{"Type": "Image", "MediaType": "GenericImage", "Data": base64.b64encode(d).decode("ascii")} for d in data] + payload = _call(config, c, "POST", "Media", {"AccountId": account, "Media": media}, "image upload") + media_ids = [str(i) for i in payload.get("MediaIds") or [] if i is not None] + if len(media_ids) != len(media): + raise PartialApplyError( + f"Microsoft stored {len(media_ids)} of {len(media)} images (media ids {media_ids}) without saying why; " + "check the account's image library before drafting again.", + created={"media_ids": media_ids}, + ) + progress.created["media_ids"] = media_ids + progress.done.append(f"uploaded {len(media_ids)} image(s) to the media library (media ids {', '.join(media_ids)})") + + extensions = [_image_extension(c, mid, p) for mid, p in zip(media_ids, payloads, strict=True)] + payload = progress.step("Creating the image extensions", lambda: _call( + config, c, "POST", "AdExtensions", {"AccountId": account, "AdExtensions": extensions}, "image extensions")) + ids = [str((i or {}).get("Id")) for i in payload.get("AdExtensionIdentities") or [] if i and i.get("Id")] + progress.created["extension_ids"] = ids + progress.done.append(f"created image extension(s) {', '.join(ids)}") + progress.step("Linking the image extensions", lambda: _call(config, c, "POST", "AdExtensionsAssociations/Set", { + "AccountId": account, "AssociationType": c["association_type"], + "AdExtensionIdToEntityIdAssociations": [{"AdExtensionId": int(i), "EntityId": int(c["entity_id"])} for i in ids], + }, "image extension links")) + return {"media_ids": media_ids, "extension_ids": ids, "linked_to": c["entity_name"], "layouts": c["layouts"], + "next": "The images go through Microsoft's editorial review; get_microsoft_ad_extensions shows each " + "extension's editorial_status."} diff --git a/src/adloop/microsoft_ads/read.py b/src/adloop/microsoft_ads/read.py new file mode 100644 index 00000000..857820a1 --- /dev/null +++ b/src/adloop/microsoft_ads/read.py @@ -0,0 +1,1263 @@ +"""Microsoft Advertising read and diagnostic tools. + +Every function takes ``config`` first and an ``ad_account_id`` that falls +back to ``microsoft_ads.ad_account_id``. Output follows the other ad +platforms: money in account currency, the status of every level of the +hierarchy, ``insights[]`` with computed findings, ``compact`` mode for +audits. + +Structure comes from Campaign Management (campaigns, location criteria, ad +groups, keywords, ads, UET tags, conversion goals); numbers come from the +Reporting service, which builds a CSV asynchronously (see +:func:`adloop.microsoft_ads.client.run_report`). +""" + +from __future__ import annotations + +from datetime import date, datetime, timedelta, timezone +from typing import TYPE_CHECKING, Any + +from adloop.microsoft_ads import client as _client +from adloop.microsoft_ads.auth import MicrosoftAdsApiError +from adloop.microsoft_ads.client import campaign_request, customer_request, report_time + +if TYPE_CHECKING: + from adloop.config import AdLoopConfig + +CAMPAIGN_TYPES = "Search, Shopping, DynamicSearchAds, Audience, PerformanceMax" +AD_TYPES = ["ResponsiveSearch", "ExpandedText", "DynamicSearch", "ResponsiveAd"] +_GOAL_TYPES_WITHOUT_IN_STORE = "Url, Duration, PagesViewedPerVisit, Event, AppInstall, OfflineConversion" +CONVERSION_GOAL_TYPES = _GOAL_TYPES_WITHOUT_IN_STORE + ", InStoreTransaction" +# Asking for InStoreTransaction goals fails the whole query for accounts +# outside Microsoft's in-store pilot, which is almost all of them. +_IN_STORE_PILOT_CODES = {"InStoreTransactionPilotNotEnabledForCustomer", "5359"} + +# Microsoft time zone names → IANA, for "today" in the account's zone. Reports +# take Microsoft's own name (ReportTimeZone) directly. From Microsoft's time +# zone mapping table (advertising/scripts/concepts/timezone-mapping), plus the +# spellings its time zones guide uses for the same zones. Where the two +# disagree on the zone itself, the offset the guide states wins: Midway +# Island and Samoa is UTC-11 (the table's Pacific/Apia is UTC+13), the +# guide's Athens zone UTC+2, International Date Line West UTC-12, and +# Astana/Dhaka and Almaty/Novosibirsk UTC+6. Every value of the API's +# TimeZoneType enum (customer-management-service/timezonetype) is covered. +_TIME_ZONES = { + "AbuDhabiMuscat": "Asia/Dubai", + "Adelaide": "Australia/Adelaide", + "Alaska": "America/Anchorage", + "AlmatyNovosibirsk": "Asia/Omsk", + "Almaty_Novosibirsk": "Asia/Omsk", + "AmsterdamBerlinBernRomeStockholmVienna": "Europe/Berlin", + "Arizona": "America/Phoenix", + "AstanaDhaka": "Asia/Dhaka", + "AthensBuchartestIstanbul": "Europe/Athens", + "AthensBuckarestIstanbul": "Europe/Athens", + "AthensIslandanbulMinsk": "Europe/Minsk", + "AtlanticTimeCanada": "America/Halifax", + "AucklandWellington": "Pacific/Auckland", + "Azores": "Atlantic/Azores", + "Baghdad": "Asia/Baghdad", + "BakuTbilisiYerevan": "Asia/Baku", + "BangkokHanoiJakarta": "Asia/Bangkok", + "BeijingChongqingHongKongUrumqi": "Asia/Shanghai", + "BelgradeBratislavaBudapestLjubljanaPrague": "Europe/Budapest", + "BogotaLimaQuito": "America/Bogota", + "Brasilia": "America/Sao_Paulo", + "Brisbane": "Australia/Brisbane", + "BrusselsCopenhagenMadridParis": "Europe/Paris", + "Bucharest": "Europe/Bucharest", + "BuenosAiresGeorgetown": "America/Buenos_Aires", + "Cairo": "Africa/Cairo", + "CanberraMelbourneSydney": "Australia/Sydney", + "CapeVerdeIsland": "Atlantic/Cape_Verde", + "CaracasLaPaz": "America/Caracas", + "CasablancaMonrovia": "Africa/Casablanca", + "CentralAmerica": "America/Guatemala", + "CentralTimeUSCanada": "America/Chicago", + "ChennaiKolkataMumbaiNewDelhi": "Asia/Calcutta", + "ChihuahuaLaPazMazatlan": "America/Chihuahua", + "Darwin": "Australia/Darwin", + "EasternTimeUSCanada": "America/New_York", + "Ekaterinburg": "Asia/Yekaterinburg", + "FijiKamchatkaMarshallIsland": "Pacific/Fiji", + "Greenland": "America/Godthab", + "GreenwichMeanTimeDublinEdinburghLisbonLondon": "Europe/London", + "GuadalajaraMexicoCityMonterrey": "America/Mexico_City", + "GuamPortMoresby": "Pacific/Port_Moresby", + "HararePretoria": "Africa/Harare", + "Hawaii": "Pacific/Honolulu", + "HelsinkiKyivRigaSofiaTallinnVilnius": "Europe/Kyiv", + "Hobart": "Australia/Hobart", + "IndianaEast": "America/Indianapolis", + "InternationalDateLineWest": "Etc/GMT+12", + "IrkutskUlaanBataar": "Asia/Irkutsk", + "IslamabadKarachiTashkent": "Asia/Karachi", + "IslandamabadKarachiTashkent": "Asia/Karachi", + "Jerusalem": "Asia/Jerusalem", + "Kabul": "Asia/Kabul", + "Kathmandu": "Asia/Kathmandu", + "Krasnoyarsk": "Asia/Krasnoyarsk", + "KualaLumpurSingapore": "Asia/Singapore", + "KuwaitRiyadh": "Asia/Riyadh", + "MagadanSolomonIslandNewCaledonia": "Asia/Magadan", + "MidAtlantic": "America/Noronha", + "MidwayIslandAndSamoa": "Pacific/Pago_Pago", + "MidwayIslandand_Samoa": "Pacific/Pago_Pago", + "MoscowStPetersburgVolgograd": "Europe/Moscow", + "MountainTimeUSCanada": "America/Denver", + "MountainTime_US_Canada": "America/Denver", + "Nairobi": "Africa/Nairobi", + "Newfoundland": "America/St_Johns", + "Nukualofa": "Pacific/Tongatapu", + "OsakaSapporoTokyo": "Asia/Tokyo", + "PacificTimeUSCanadaTijuana": "America/Los_Angeles", + "Perth": "Australia/Perth", + "Rangoon": "Asia/Yangon", + "Santiago": "America/Santiago", + "SarajevoSkopjeWarsawZagreb": "Europe/Warsaw", + "Saskatchewan": "America/Regina", + "Seoul": "Asia/Seoul", + "SolomonIslandNewCaledonia": "Asia/Magadan", + "SriJayawardenepura": "Asia/Colombo", + "Taipei": "Asia/Taipei", + "Tehran": "Asia/Tehran", + "Vladivostok": "Asia/Vladivostok", + "WestCentralAfrica": "Africa/Lagos", + "Yakutsk": "Asia/Yakutsk", + "Yangon": "Asia/Yangon", +} + +_PERFORMANCE_LEVELS = { + "account": "AccountPerformanceReportRequest", + "campaign": "CampaignPerformanceReportRequest", + "ad_group": "AdGroupPerformanceReportRequest", + "keyword": "KeywordPerformanceReportRequest", + "ad": "AdPerformanceReportRequest", +} +_LEVEL_COLUMNS = { + "account": ["AccountId", "AccountName"], + "campaign": ["CampaignId", "CampaignName", "CampaignStatus", "CampaignType"], + "ad_group": ["CampaignId", "CampaignName", "CampaignStatus", "AdGroupId", "AdGroupName", "Status"], + "keyword": [ + "CampaignName", "CampaignStatus", "AdGroupId", "AdGroupName", "AdGroupStatus", + "KeywordId", "Keyword", "KeywordStatus", "BidMatchType", "QualityScore", + ], + "ad": [ + "CampaignName", "CampaignStatus", "AdGroupId", "AdGroupName", "AdGroupStatus", + "AdId", "AdType", "AdStatus", "FinalUrl", + ], +} +# Conversions, ConversionRate, CostPerConversion and AllConversions are +# deprecated: keyword and search-query reports return 0 for them. The +# "Qualified" columns are their replacements; rate and CPA are computed here. +_METRIC_COLUMNS = [ + "Impressions", "Clicks", "Spend", "Ctr", "AverageCpc", "ConversionsQualified", "Revenue", +] +# Goals that a UET tag has to report; offline, app-install and in-store +# goals arrive by import or another channel and need no tag. +_TAG_GOAL_TYPES = {"Url", "Duration", "PagesViewedPerVisit", "Event"} +# Impression share, the share lost to budget and to rank (summary rows only). +_SHARE_NAMES = { + "ImpressionSharePercent": "impression_share_pct", + "ImpressionLostToBudgetPercent": "lost_to_budget_pct", + "ImpressionLostToRankAggPercent": "lost_to_rank_pct", +} +_SHARE_COLUMNS = list(_SHARE_NAMES) +_BREAKDOWNS = ("date", "device") + +_INTENT_OPTIONS = { + "PeopleIn": "people in the targeted locations", + "PeopleInOrSearchingForOrViewingPages": "people in, searching for or viewing pages about the locations", + "PeopleSearchingForOrViewingPages": "people searching for or viewing pages about the locations", +} + +_account_cache: dict[str, dict] = {} + + +# --------------------------------------------------------------------------- +# Helpers +# --------------------------------------------------------------------------- + + +def reset_account_cache() -> None: + _account_cache.clear() + + +def resolve_account(config: AdLoopConfig, ad_account_id: str = "") -> str: + account = str(ad_account_id or config.microsoft_ads.ad_account_id or "").strip() + if not account: + from adloop.runtime import default_setting_hint + + raise ValueError( + "ad_account_id is required: pass it (see list_microsoft_ads_accounts) or " + + default_setting_hint("microsoft_ads.ad_account_id", "Settings → Microsoft Ads") + + "." + ) + return account + + +def account_meta(config: AdLoopConfig, ad_account_id: str = "", *, fresh: bool = False) -> dict: + """Name, number, currency, time zone, status and manager of an ad account. + + Cached per process for the currency and time zone the reports need; a + hosted server never caches, so one tenant cannot read another's entry. + """ + from adloop.runtime import deployment_mode + + account = resolve_account(config, ad_account_id) + cacheable = deployment_mode() != "server" + if cacheable and not fresh and account in _account_cache: + return _account_cache[account] + data = customer_request(config, "Account/Query", {"AccountId": account}, account_id=account) + acct = data.get("Account") or {} + meta = { + "ad_account_id": str(acct.get("Id") or account), + "name": acct.get("Name") or "", + "number": acct.get("Number") or "", + "currency": acct.get("CurrencyCode") or "", + "time_zone": acct.get("TimeZone") or "", + "status": acct.get("AccountLifeCycleStatus") or "", + "pause_reason": acct.get("PauseReason"), + "customer_id": str(acct.get("ParentCustomerId") or config.microsoft_ads.customer_id or ""), + } + if cacheable: + _account_cache[account] = meta + return meta + + +def _customer(config: AdLoopConfig, meta: dict) -> str: + return str(config.microsoft_ads.customer_id or meta.get("customer_id") or "") + + +def _zone(name: str): + from zoneinfo import ZoneInfo, ZoneInfoNotFoundError + + try: + return ZoneInfo(_TIME_ZONES.get(name, "UTC")) + except (ZoneInfoNotFoundError, ValueError): + return timezone.utc + + +def zone_note(name: str) -> str | None: + """A visible note when the account's time zone is not one AdLoop knows.""" + if not name or name in _TIME_ZONES: + return None + return (f"The account's time zone '{name}' is not in AdLoop's Microsoft time zone table, so the default " + "window and 'today' were worked out in UTC; the last day may be off by one. Pass explicit dates.") + + +def _parse_date(value: str, *, default: date) -> date: + if not value: + return default + try: + return datetime.strptime(value.strip(), "%Y-%m-%d").date() + except ValueError as exc: + raise ValueError(f"Invalid date '{value}' — use YYYY-MM-DD (e.g. 2026-10-01).") from exc + + +def report_window(date_range_start: str, date_range_end: str, time_zone: str) -> tuple[date, date]: + """Account-local days; default the 30 days ending yesterday.""" + today = datetime.now(_zone(time_zone)).date() + end = _parse_date(date_range_end, default=today - timedelta(days=1)) + start = _parse_date(date_range_start, default=end - timedelta(days=29)) + if start > end: + raise ValueError("date_range_start must not be after date_range_end.") + if end > today: + raise ValueError("date_range_end cannot be in the future.") + return start, end + + +def _num(value: Any) -> float | None: + """'1,234.56', '3.70%', '--' → float; percentages stay in percent units.""" + if value is None: + return None + text = str(value).strip().replace(",", "").rstrip("%") + if text in ("", "--", "-"): + return None + try: + return float(text) + except ValueError: + return None + + +def _money(value: Any) -> float | None: + if isinstance(value, dict): + value = value.get("Amount") + number = _num(value) + return None if number is None else round(number, 2) + + +def _ms_date(value: Any) -> str | None: + if isinstance(value, dict) and value.get("Year"): + return f"{int(value['Year']):04d}-{int(value['Month']):02d}-{int(value['Day']):02d}" + return None + + +def _check_choice(name: str, value: Any, allowed) -> None: + if value not in allowed: + raise ValueError(f"{name} must be one of {sorted(allowed)}, got {value!r}.") + + +# --------------------------------------------------------------------------- +# Accounts +# --------------------------------------------------------------------------- + + +def list_microsoft_ads_accounts(config: AdLoopConfig) -> dict: + """The signed-in user and every ad account they can reach.""" + user_payload = customer_request(config, "User/Query", {"UserId": None}) + user = user_payload.get("User") or {} + roles = user_payload.get("CustomerRoles") or [] + accounts: list[dict] = [] + page = 0 + while page < 20: + payload = customer_request( + config, + "Accounts/Search", + { + "Predicates": [{"Field": "UserId", "Operator": "Equals", "Value": str(user.get("Id") or "")}], + "Ordering": None, + "PageInfo": {"Index": page, "Size": 100}, + }, + ) + batch = payload.get("Accounts") or [] + accounts.extend(a for a in batch if isinstance(a, dict)) + if len(batch) < 100: + break + page += 1 + return { + "user": { + "user_id": user.get("Id"), + "user_name": user.get("UserName"), + "email": (user.get("ContactInfo") or {}).get("Email"), + }, + "customers": [ + {"customer_id": r.get("CustomerId"), "role_id": r.get("RoleId"), + "account_ids": r.get("AccountIds")} + for r in roles if isinstance(r, dict) + ], + "accounts": [ + { + "ad_account_id": str(a.get("Id")), + "name": a.get("Name"), + "number": a.get("Number"), + "customer_id": str(a.get("ParentCustomerId") or ""), + "currency": a.get("CurrencyCode"), + "time_zone": a.get("TimeZone"), + "status": a.get("AccountLifeCycleStatus"), + "pause_reason": a.get("PauseReason"), + } + for a in accounts + ], + "total": len(accounts), + "note": ( + "Pass ad_account_id to the other Microsoft tools, or set microsoft_ads.ad_account_id " + "and microsoft_ads.customer_id in the config." + ), + } + + +# --------------------------------------------------------------------------- +# Structure +# --------------------------------------------------------------------------- + + +# Campaign fields Microsoft returns only when asked for. Previews and the +# changed-since-the-draft checks depend on the first two: a MaxConversions +# campaign's target CPA, and whether its ad schedule runs in the account's +# or each searcher's time zone. +_CAMPAIGN_FIELDS = "AdScheduleUseSearcherTimeZone, TargetCpaInMaxConversion" + + +def _campaigns(config: AdLoopConfig, account: str, customer: str, *, with_goals: bool = False) -> list[dict]: + body: dict[str, Any] = {"AccountId": account, "CampaignType": CAMPAIGN_TYPES, + "ReturnAdditionalFields": _CAMPAIGN_FIELDS} + if with_goals: + # GoalIds only come back when asked for. + body["ReturnAdditionalFields"] = f"{_CAMPAIGN_FIELDS}, CampaignConversionGoal" + payload = campaign_request( + config, "Campaigns/QueryByAccountId", body, account_id=account, customer_id=customer, + ) + return [c for c in payload.get("Campaigns") or [] if isinstance(c, dict)] + + +def _criterions(config: AdLoopConfig, account: str, customer: str, campaign_id: str, kind: str) -> list[dict]: + payload = campaign_request( + config, "CampaignCriterions/QueryByIds", + {"CampaignCriterionIds": None, "CampaignId": campaign_id, "CriterionType": kind}, + account_id=account, customer_id=customer, + ) + return [c for c in payload.get("CampaignCriterions") or [] if isinstance(c, dict)] + + +def _ad_groups(config: AdLoopConfig, account: str, customer: str, campaign_id: str) -> list[dict]: + payload = campaign_request( + config, "AdGroups/QueryByCampaignId", {"CampaignId": campaign_id}, + account_id=account, customer_id=customer, + ) + return [g for g in payload.get("AdGroups") or [] if isinstance(g, dict)] + + +def _keywords(config: AdLoopConfig, account: str, customer: str, ad_group_id: str) -> list[dict]: + payload = campaign_request( + config, "Keywords/QueryByAdGroupId", {"AdGroupId": ad_group_id}, + account_id=account, customer_id=customer, + ) + return [k for k in payload.get("Keywords") or [] if isinstance(k, dict)] + + +def _ads(config: AdLoopConfig, account: str, customer: str, ad_group_id: str) -> list[dict]: + payload = campaign_request( + config, "Ads/QueryByAdGroupId", {"AdGroupId": ad_group_id, "AdTypes": AD_TYPES}, + account_id=account, customer_id=customer, + ) + return [a for a in payload.get("Ads") or [] if isinstance(a, dict)] + + +def _conversion_goals(config: AdLoopConfig, account: str, customer: str) -> list[dict]: + """Every conversion goal; in-store ones only where the account is in Microsoft's pilot.""" + def query(types: str) -> dict: + return campaign_request( + config, "ConversionGoals/QueryByIds", {"ConversionGoalIds": None, "ConversionGoalTypes": types}, + account_id=account, customer_id=customer, + ) + + try: + payload = query(CONVERSION_GOAL_TYPES) + except MicrosoftAdsApiError as exc: + if not set(exc.codes) & _IN_STORE_PILOT_CODES: + raise + payload = query(_GOAL_TYPES_WITHOUT_IN_STORE) + return [g for g in payload.get("ConversionGoals") or [] if isinstance(g, dict)] + + +def _bidding(scheme: dict | None) -> dict: + scheme = scheme or {} + kind = str(scheme.get("Type") or "") + out: dict[str, Any] = {"strategy": kind.replace("BiddingScheme", "") or None} + for key, label in (("MaxCpc", "max_cpc"), ("TargetCpa", "target_cpa"), ("TargetRoas", "target_roas")): + if scheme.get(key) is not None: + out[label] = _money(scheme.get(key)) + return out + + +def _location_summary(locations: list[dict], intent: list[dict], radius: list[dict]) -> dict: + included, excluded = [], [] + for c in locations + radius: + crit = c.get("Criterion") or {} + if crit.get("Type") == "RadiusCriterion": + label = f"{crit.get('Name') or 'radius'} ({crit.get('Radius')} {crit.get('RadiusUnit') or ''})".strip() + else: + label = crit.get("DisplayName") or str(crit.get("LocationId") or "") + if crit.get("LocationType"): + label += f" ({crit.get('LocationType')})" + (excluded if c.get("Type") == "NegativeCampaignCriterion" else included).append(label) + option = "" + for c in intent: + option = str((c.get("Criterion") or {}).get("IntentOption") or "") + return { + "included": included, + "excluded": excluded, + "intent": option or None, + "intent_meaning": _INTENT_OPTIONS.get(option), + } + + +def campaign_summary(campaign: dict, targeting: dict | None = None) -> dict: + budget_id = campaign.get("BudgetId") + shared = bool(budget_id) and str(budget_id) not in ("0", "None") + return { + "campaign_id": str(campaign.get("Id")), + "name": campaign.get("Name"), + "status": campaign.get("Status"), + "campaign_type": campaign.get("CampaignType"), + "daily_budget": _money(campaign.get("DailyBudget")), + "budget_type": campaign.get("BudgetType"), + "shared_budget_id": str(budget_id) if shared else None, + "bidding": _bidding(campaign.get("BiddingScheme")), + "languages": campaign.get("Languages") or [], + "time_zone": campaign.get("TimeZone"), + "goal_ids": [str(g) for g in campaign.get("GoalIds") or []], + "tracking_template": campaign.get("TrackingUrlTemplate") or "", + "final_url_suffix": campaign.get("FinalUrlSuffix") or "", + "locations": targeting, + } + + +def get_microsoft_campaigns( + config: AdLoopConfig, *, ad_account_id: str = "", include_targeting: bool = True, +) -> dict: + """Campaigns with budget, bidding, languages and location targeting.""" + meta = account_meta(config, ad_account_id) + account, customer = meta["ad_account_id"], _customer(config, meta) + rows = [] + for c in _campaigns(config, account, customer, with_goals=True): + targeting = None + if include_targeting: + cid = str(c.get("Id")) + targeting = _location_summary( + _criterions(config, account, customer, cid, "Location"), + _criterions(config, account, customer, cid, "LocationIntent"), + _criterions(config, account, customer, cid, "Radius"), + ) + rows.append(campaign_summary(c, targeting)) + + insights: list[str] = [] + if meta["status"] and meta["status"] != "Active": + insights.append( + f"The ad account is {meta['status']}" + + (f" (pause reason {meta['pause_reason']})" if meta.get("pause_reason") else "") + + ": nothing serves until it is Active." + ) + for c in rows: + live = c["status"] == "Active" + if c["status"] in ("BudgetPaused", "BudgetAndManualPaused"): + insights.append(f"Campaign '{c['name']}' is paused by its budget ({c['status']}).") + if c["status"] == "Suspended": + insights.append(f"Campaign '{c['name']}' is Suspended by Microsoft.") + loc = c["locations"] + if loc is not None and live and not loc["included"]: + insights.append(f"Campaign '{c['name']}' targets no location, so it can serve everywhere.") + if loc is not None and live and loc["intent"] and loc["intent"] != "PeopleIn": + insights.append( + f"Campaign '{c['name']}' reaches {loc['intent_meaning']}, not only people in them; " + "for a local service business 'PeopleIn' keeps clicks local." + ) + if c["shared_budget_id"]: + insights.append( + f"Campaign '{c['name']}' uses shared budget {c['shared_budget_id']}: its daily " + "amount is set on that budget, not on the campaign." + ) + return { + "ad_account_id": account, + "account_name": meta["name"], + "currency": meta["currency"], + "time_zone": meta["time_zone"], + "campaigns": rows, + "total_campaigns": len(rows), + "insights": insights, + } + + +def load_ad_groups(config: AdLoopConfig, account: str, customer: str, campaign_id: str = "") -> list[tuple[dict, dict]]: + pairs = [] + for c in _campaigns(config, account, customer): + if campaign_id and str(c.get("Id")) != str(campaign_id): + continue + for g in _ad_groups(config, account, customer, str(c.get("Id"))): + pairs.append((g, c)) + return pairs + + +def get_microsoft_ad_groups(config: AdLoopConfig, *, ad_account_id: str = "", campaign_id: str = "") -> dict: + """Ad groups with bid, network, language, dates and their campaign's status.""" + meta = account_meta(config, ad_account_id) + account, customer = meta["ad_account_id"], _customer(config, meta) + rows = [] + for g, c in load_ad_groups(config, account, customer, campaign_id.strip()): + rows.append({ + "ad_group_id": str(g.get("Id")), + "name": g.get("Name"), + "status": g.get("Status"), + "campaign_id": str(c.get("Id")), + "campaign_name": c.get("Name"), + "campaign_status": c.get("Status"), + "cpc_bid": _money(g.get("CpcBid")), + "network": g.get("Network"), + "language": g.get("Language"), + "audience_ads_bid_adjustment": g.get("AudienceAdsBidAdjustment"), + "start_date": _ms_date(g.get("StartDate")), + "end_date": _ms_date(g.get("EndDate")), + }) + insights: list[str] = [] + syndicated = [r for r in rows if r["status"] == "Active" and r["network"] == "OwnedAndOperatedAndSyndicatedSearch"] + if syndicated: + insights.append( + f"{len(syndicated)} active ad group(s) also run on syndicated search partners " + "(OwnedAndOperatedAndSyndicatedSearch); set OwnedAndOperatedOnly to keep ads on Bing, " + "Yahoo and AOL only." + ) + audience = [ + r for r in rows + if r["status"] == "Active" and r["audience_ads_bid_adjustment"] not in (None, -100) + ] + if audience: + insights.append( + f"{len(audience)} active ad group(s) can show on the Microsoft Audience Network " + "(display placements); a bid adjustment of -100 turns that off." + ) + expired = [r for r in rows if r["status"] == "Expired"] + if expired: + insights.append(f"{len(expired)} ad group(s) have passed their end date (Expired).") + return {"ad_account_id": account, "currency": meta["currency"], "ad_groups": rows, + "total_ad_groups": len(rows), "insights": insights} + + +def get_microsoft_keywords( + config: AdLoopConfig, *, ad_account_id: str = "", campaign_id: str = "", ad_group_id: str = "", +) -> dict: + """Keywords with match type, bid, status and editorial review, with parent statuses.""" + meta = account_meta(config, ad_account_id) + account, customer = meta["ad_account_id"], _customer(config, meta) + rows = [] + for g, c in load_ad_groups(config, account, customer, campaign_id.strip()): + if ad_group_id and str(g.get("Id")) != str(ad_group_id): + continue + for k in _keywords(config, account, customer, str(g.get("Id"))): + rows.append({ + "keyword_id": str(k.get("Id")), + "text": k.get("Text"), + "match_type": k.get("MatchType"), + "bid": _money(k.get("Bid")), + "status": k.get("Status"), + "editorial_status": k.get("EditorialStatus"), + "ad_group_id": str(g.get("Id")), + "ad_group_name": g.get("Name"), + "ad_group_status": g.get("Status"), + "campaign_name": c.get("Name"), + "campaign_status": c.get("Status"), + "campaign_bidding": _bidding(c.get("BiddingScheme")).get("strategy"), + }) + insights: list[str] = [] + disapproved = [r for r in rows if r["editorial_status"] == "Disapproved"] + if disapproved: + insights.append( + f"{len(disapproved)} keyword(s) were disapproved in editorial review: " + + ", ".join(f"'{r['text']}'" for r in disapproved[:5]) + "." + ) + broad_manual = [ + r for r in rows + if r["match_type"] == "Broad" and r["status"] == "Active" + and r["campaign_bidding"] in ("ManualCpc", "EnhancedCpc") + ] + if broad_manual: + insights.append( + f"{len(broad_manual)} active broad-match keyword(s) sit in manual-bid campaigns, the " + "combination that wastes the most spend; use phrase/exact or a conversion-based strategy." + ) + return {"ad_account_id": account, "currency": meta["currency"], "keywords": rows, + "total_keywords": len(rows), "insights": insights} + + +def _texts(items: Any) -> list[str]: + out = [] + for item in items or []: + if isinstance(item, dict): + asset = item.get("Asset") or {} + text = asset.get("Text") or item.get("Text") + pin = item.get("PinnedField") + if text: + out.append(f"{text} [pinned {pin}]" if pin else text) + return out + + +def get_microsoft_ads( + config: AdLoopConfig, *, ad_account_id: str = "", campaign_id: str = "", ad_group_id: str = "", +) -> dict: + """Ads with headlines, descriptions, final URLs, status and editorial review.""" + meta = account_meta(config, ad_account_id) + account, customer = meta["ad_account_id"], _customer(config, meta) + rows = [] + for g, c in load_ad_groups(config, account, customer, campaign_id.strip()): + if ad_group_id and str(g.get("Id")) != str(ad_group_id): + continue + for a in _ads(config, account, customer, str(g.get("Id"))): + rows.append({ + "ad_id": str(a.get("Id")), + "type": a.get("Type"), + "status": a.get("Status"), + "editorial_status": a.get("EditorialStatus"), + "headlines": _texts(a.get("Headlines")) or [t for t in (a.get("TitlePart1"), a.get("TitlePart2"), a.get("TitlePart3")) if t], + "descriptions": _texts(a.get("Descriptions")) or [t for t in (a.get("Text"), a.get("TextPart2")) if t], + "path1": a.get("Path1"), + "path2": a.get("Path2"), + "final_urls": a.get("FinalUrls") or [], + "ad_group_id": str(g.get("Id")), + "ad_group_name": g.get("Name"), + "ad_group_status": g.get("Status"), + "campaign_name": c.get("Name"), + "campaign_status": c.get("Status"), + }) + insights: list[str] = [] + disapproved = [r for r in rows if r["editorial_status"] in ("Disapproved", "Inactive")] + if disapproved: + insights.append(f"{len(disapproved)} ad(s) are Disapproved or Inactive in editorial review.") + live_groups = {r["ad_group_id"] for r in rows if r["status"] == "Active"} + all_groups = {r["ad_group_id"] for r in rows} + no_live = all_groups - live_groups + if no_live: + insights.append(f"{len(no_live)} ad group(s) have no active ad, so they cannot serve.") + return {"ad_account_id": account, "ads": rows, "total_ads": len(rows), "insights": insights} + + +# --------------------------------------------------------------------------- +# Reports +# --------------------------------------------------------------------------- + + +def _report( + config: AdLoopConfig, meta: dict, report_type: str, columns: list[str], start: date, end: date, + *, aggregation: str = "Summary", scope_campaign_id: str = "", +) -> list[dict]: + account = meta["ad_account_id"] + # AccountIds and Campaigns are a union, not a filter: a campaign scope + # must leave AccountIds out or the report covers the whole account. + scope: dict[str, Any] = ( + {"Campaigns": [{"AccountId": account, "CampaignId": scope_campaign_id}]} + if scope_campaign_id else {"AccountIds": [account]} + ) + request = { + "Type": report_type, + "ReportName": f"AdLoop {report_type}", + "Aggregation": aggregation, + "Columns": columns, + "Scope": scope, + "Time": report_time(start, end, meta["time_zone"]), + } + return _client.run_report(config, request, account_id=account, customer_id=_customer(config, meta)) + + +def _metrics(row: dict) -> dict: + clicks = int(_num(row.get("Clicks")) or 0) + impressions = int(_num(row.get("Impressions")) or 0) + spend = round(_num(row.get("Spend")) or 0.0, 2) + conversions = _num(row.get("ConversionsQualified")) or 0.0 + ctr = _num(row.get("Ctr")) + out = { + "impressions": impressions, + "clicks": clicks, + "spend": spend, + "ctr": round(ctr / 100, 4) if ctr is not None else (round(clicks / impressions, 4) if impressions else None), + "cpc": _money(row.get("AverageCpc")) if row.get("AverageCpc") not in (None, "") else (round(spend / clicks, 2) if clicks else None), + "conversions": round(conversions, 2), + "conversion_rate": round(conversions / clicks, 4) if clicks else None, + "cpa": round(spend / conversions, 2) if conversions else None, + "revenue": _money(row.get("Revenue")), + } + for column, name in _SHARE_NAMES.items(): + if row.get(column) not in (None, ""): + out[name] = _num(row.get(column)) + return out + + +_ID_RENAMES = { + "AccountId": "ad_account_id", "AccountName": "account_name", + "CampaignId": "campaign_id", "CampaignName": "campaign_name", "CampaignStatus": "campaign_status", + "CampaignType": "campaign_type", "AdGroupId": "ad_group_id", "AdGroupName": "ad_group_name", + "AdGroupStatus": "ad_group_status", "Status": "ad_group_status", "KeywordId": "keyword_id", + "Keyword": "keyword", "KeywordStatus": "keyword_status", "BidMatchType": "match_type", + "QualityScore": "quality_score", "AdId": "ad_id", "AdType": "ad_type", "AdStatus": "ad_status", + "FinalUrl": "final_url", "TimePeriod": "date", "DeviceType": "device", +} + + +def _totals(rows: list[dict], currency: str) -> dict: + spend = round(sum(r["spend"] for r in rows), 2) + clicks = sum(r["clicks"] for r in rows) + impressions = sum(r["impressions"] for r in rows) + conversions = round(sum(r["conversions"] for r in rows), 2) + return { + "spend": spend, "impressions": impressions, "clicks": clicks, "conversions": conversions, + "ctr": round(clicks / impressions, 4) if impressions else None, + "cpc": round(spend / clicks, 2) if clicks else None, + "cpa": round(spend / conversions, 2) if conversions else None, + "currency": currency, + } + + +def get_microsoft_performance( + config: AdLoopConfig, + *, + ad_account_id: str = "", + level: str = "campaign", + date_range_start: str = "", + date_range_end: str = "", + breakdown: str = "", + campaign_id: str = "", + compact: bool = False, +) -> dict: + """Spend, clicks, conversions, CPA and impression share per level, statuses joined.""" + level = (level or "campaign").strip().lower() + breakdown = (breakdown or "").strip().lower() + _check_choice("level", level, _PERFORMANCE_LEVELS) + if breakdown: + _check_choice("breakdown", breakdown, _BREAKDOWNS) + if level == "account" and campaign_id.strip(): + raise ValueError("campaign_id narrows campaign, ad_group, keyword and ad reports; " + "the account level covers the whole account.") + meta = account_meta(config, ad_account_id) + start, end = report_window(date_range_start, date_range_end, meta["time_zone"]) + columns = list(_LEVEL_COLUMNS[level]) + _METRIC_COLUMNS + aggregation = "Summary" + if breakdown == "date": + columns.insert(0, "TimePeriod") + aggregation = "Daily" + elif breakdown == "device": + columns.insert(0, "DeviceType") + elif level in ("campaign", "ad_group"): + columns += _SHARE_COLUMNS + raw = _report(config, meta, _PERFORMANCE_LEVELS[level], columns, start, end, + aggregation=aggregation, scope_campaign_id=campaign_id.strip()) + + rows = [] + for r in raw: + row = {_ID_RENAMES[k]: v for k, v in r.items() if k in _ID_RENAMES} + row.update(_metrics(r)) + row["currency"] = meta["currency"] + rows.append(row) + rows.sort(key=lambda x: x["spend"], reverse=True) + + insights: list[str] = [] + name_key = {"campaign": "campaign_name", "ad_group": "ad_group_name", "keyword": "keyword", "ad": "ad_id"}.get(level) + zero = [r for r in rows if r["spend"] > 0 and not r["conversions"]] if name_key and not breakdown else [] + if zero: + insights.append( + f"{len(zero)} {level.replace('_', ' ')}(s) spent {round(sum(r['spend'] for r in zero), 2)} " + f"{meta['currency']} with zero conversions: " + + ", ".join(str(r.get(name_key)) for r in zero[:5]) + + ". Check get_microsoft_conversion_setup before cutting them: calls may convert " + "outside Microsoft's view." + ) + budget_lost = [r for r in rows if (r.get("lost_to_budget_pct") or 0) >= 20 and r["conversions"]] + if budget_lost: + insights.append( + f"{len(budget_lost)} converting {level.replace('_', ' ')}(s) lose 20%+ of impressions to " + "budget: " + ", ".join(f"{r.get(name_key)} ({r['lost_to_budget_pct']:g}%)" for r in budget_lost[:5]) + "." + ) + paused = [ + r for r in rows if r["spend"] > 0 + and {r.get("campaign_status"), r.get("ad_group_status"), r.get("keyword_status"), r.get("ad_status")} + & {"Paused", "Deleted", "BudgetPaused", "BudgetAndManualPaused", "Expired"} + ] + if paused and not breakdown: + insights.append( + f"{len(paused)} row(s) spent in this window but sit under a paused, deleted or " + "expired level now." + ) + if not rows: + insights.append("No delivery in this window.") + + result: dict[str, Any] = { + "ad_account_id": meta["ad_account_id"], + "level": level, + "breakdown": breakdown or None, + "date_range": {"start": start.isoformat(), "end": end.isoformat(), "time_zone": meta["time_zone"]}, + "currency": meta["currency"], + "totals": _totals(rows, meta["currency"]), + "insights": ([zone_note(meta["time_zone"])] if zone_note(meta["time_zone"]) else []) + insights, + "note": ( + "Conversions are the account's conversion goals that count toward 'Conversions' " + "(goals excluded from bidding appear only in All conversions). Ctr and conversion " + "rate are fractions; impression share columns are percentages." + ), + } + if compact: + result.update(compact=True, total_rows=len(rows), rows_top_spend=rows[:10], + zero_conversion_spenders=zero[:10]) + else: + result.update(rows=rows, total_rows=len(rows)) + return result + + +def get_microsoft_search_terms( + config: AdLoopConfig, + *, + ad_account_id: str = "", + date_range_start: str = "", + date_range_end: str = "", + campaign_id: str = "", + min_clicks: int = 2, + compact: bool = False, +) -> dict: + """What people searched before clicking, with the keyword and match type that matched.""" + meta = account_meta(config, ad_account_id) + start, end = report_window(date_range_start, date_range_end, meta["time_zone"]) + columns = [ + "CampaignName", "CampaignStatus", "AdGroupName", "AdGroupStatus", "SearchQuery", "Keyword", + "BidMatchType", "DeliveredMatchType", "Impressions", "Clicks", "Spend", "Ctr", "AverageCpc", + "ConversionsQualified", "Revenue", + ] + raw = _report(config, meta, "SearchQueryPerformanceReportRequest", columns, start, end, + scope_campaign_id=campaign_id.strip()) + rows = [] + for r in raw: + row = { + "search_term": r.get("SearchQuery"), + "keyword": r.get("Keyword"), + "keyword_match_type": r.get("BidMatchType"), + "delivered_match_type": r.get("DeliveredMatchType"), + "campaign_name": r.get("CampaignName"), + "campaign_status": r.get("CampaignStatus"), + "ad_group_name": r.get("AdGroupName"), + "ad_group_status": r.get("AdGroupStatus"), + } + row.update(_metrics(r)) + rows.append(row) + rows.sort(key=lambda x: x["spend"], reverse=True) + waste = [r for r in rows if r["clicks"] >= max(int(min_clicks or 1), 1) and not r["conversions"]] + converters = [r for r in rows if r["conversions"]] + + insights: list[str] = [] + if waste: + insights.append( + f"{len(waste)} search term(s) with {min_clicks}+ clicks and no conversion cost " + f"{round(sum(r['spend'] for r in waste), 2)} {meta['currency']}; review them as " + "negative keyword candidates (calls may convert outside Microsoft's view)." + ) + loose = [r for r in rows if r["keyword_match_type"] in ("Exact", "Phrase") and r["delivered_match_type"] == "Broad"] + if loose: + insights.append( + f"{len(loose)} term(s) matched exact/phrase keywords as broad (close variants); " + "check them for intent drift." + ) + if not rows: + insights.append("No search terms with clicks or impressions in this window.") + + result: dict[str, Any] = { + "ad_account_id": meta["ad_account_id"], + "date_range": {"start": start.isoformat(), "end": end.isoformat()}, + "currency": meta["currency"], + "totals": _totals(rows, meta["currency"]), + "insights": ([zone_note(meta["time_zone"])] if zone_note(meta["time_zone"]) else []) + insights, + } + if compact: + result.update(compact=True, total_terms=len(rows), top_by_spend=rows[:25], + waste_candidates=waste[:25], top_converters=converters[:10]) + else: + result.update(search_terms=rows, total_terms=len(rows)) + return result + + +def get_microsoft_location_performance( + config: AdLoopConfig, + *, + ad_account_id: str = "", + date_range_start: str = "", + date_range_end: str = "", + campaign_id: str = "", + group_by: str = "city", +) -> dict: + """Where clicks came from, split into people physically there and people interested in it.""" + group_by = (group_by or "city").strip().lower() + fields = {"city": "City", "metro": "MetroArea", "state": "State", "postal_code": "PostalCode", + "most_specific": "MostSpecificLocation"} + _check_choice("group_by", group_by, fields) + meta = account_meta(config, ad_account_id) + start, end = report_window(date_range_start, date_range_end, meta["time_zone"]) + columns = list(dict.fromkeys([ + "CampaignName", "LocationType", fields[group_by], "State", "Country", + "Impressions", "Clicks", "Spend", "ConversionsQualified", + ])) + raw = _report(config, meta, "GeographicPerformanceReportRequest", columns, start, end, + scope_campaign_id=campaign_id.strip()) + merged: dict[tuple, dict] = {} + for r in raw: + key = (r.get(fields[group_by]) or "(unknown)", r.get("State") or "", r.get("LocationType") or "") + entry = merged.setdefault(key, { + "location": key[0], "state": key[1] or None, "country": r.get("Country"), + "location_type": key[2] or None, "impressions": 0, "clicks": 0, "spend": 0.0, "conversions": 0.0, + }) + m = _metrics(r) + for k in ("impressions", "clicks", "spend", "conversions"): + entry[k] += m[k] + rows = sorted(merged.values(), key=lambda x: x["spend"], reverse=True) + for r in rows: + r["spend"] = round(r["spend"], 2) + r["conversions"] = round(r["conversions"], 2) + + total_spend = round(sum(r["spend"] for r in rows), 2) + interest = [r for r in rows if r["location_type"] and "interest" in r["location_type"].lower()] + interest_spend = round(sum(r["spend"] for r in interest), 2) + insights: list[str] = [] + if total_spend and interest_spend / total_spend >= 0.1: + insights.append( + f"{round(100 * interest_spend / total_spend)}% of spend ({interest_spend} {meta['currency']}) " + "came from people searching about the area from elsewhere (location of interest). " + "Set the campaign's location intent to 'PeopleIn' to stop that." + ) + return { + "ad_account_id": meta["ad_account_id"], + "date_range": {"start": start.isoformat(), "end": end.isoformat()}, + "group_by": group_by, + "currency": meta["currency"], + "totals": {"spend": total_spend, "clicks": sum(r["clicks"] for r in rows), + "conversions": round(sum(r["conversions"] for r in rows), 2), + "spend_from_location_of_interest": interest_spend}, + "locations": rows, + "insights": ([zone_note(meta["time_zone"])] if zone_note(meta["time_zone"]) else []) + insights, + "note": "Location type 'Physical location' is where the person was; 'Location of interest' is what they searched about.", + } + + +# --------------------------------------------------------------------------- +# Conversion setup audit +# --------------------------------------------------------------------------- + + +def _check(name: str, status: str, detail: str) -> dict: + return {"check": name, "status": status, "detail": detail} + + +def get_microsoft_conversion_setup( + config: AdLoopConfig, + *, + ad_account_id: str = "", + date_range_start: str = "", + date_range_end: str = "", + min_clicks: int = 30, +) -> dict: + """Audit UET tags, conversion goals, campaign goals and recent conversions; returns a verdict.""" + meta = account_meta(config, ad_account_id) + account, customer = meta["ad_account_id"], _customer(config, meta) + start, end = report_window(date_range_start, date_range_end, meta["time_zone"]) + checks: list[dict] = [] + insights: list[str] = [] + + tags = campaign_request(config, "UetTags/QueryByIds", {"TagIds": None}, + account_id=account, customer_id=customer).get("UetTags") or [] + goals = _conversion_goals(config, account, customer) + campaigns = _campaigns(config, account, customer, with_goals=True) + + # 1. UET tag: required only by goals the tag reports (URL, duration, + # pages per visit, event). A tag no active goal uses is a loose end, not + # a broken setup. + tags = [t for t in tags if isinstance(t, dict)] + tag_goals = [g for g in goals if g.get("Status") == "Active" and g.get("Type") in _TAG_GOAL_TYPES] + if not tags: + if tag_goals: + checks.append(_check( + "uet tag", "fail", + "No UET tag exists, yet " + ", ".join(f"'{g.get('Name')}'" for g in tag_goals[:5]) + + " need one: Microsoft cannot see those site conversions.", + )) + elif goals: + checks.append(_check( + "uet tag", "info", + "No UET tag; the active goals arrive without one (offline import, app or store).", + )) + else: + checks.append(_check("uet tag", "fail", "No UET tag exists: Microsoft cannot see any site conversion.")) + for t in tags: + status = t.get("TrackingStatus") + users = [g for g in tag_goals if str(g.get("TagId") or "") == str(t.get("Id"))] + detail = { + "Active": "Receiving events.", + "Unverified": "Never received an event: the tag is not on the site, or consent blocks it.", + "Inactive": "No events in the last 24 hours.", + }.get(status, f"Tracking status {status}.") + if status == "Active": + level = "pass" + elif status in ("Unverified", "Inactive"): + level = "fail" if users or (len(tags) == 1 and tag_goals) else "warn" + if level == "warn": + detail += " No active goal uses this tag, so nothing depends on it." + else: + level = "warn" + if users: + detail += " Used by " + ", ".join(f"'{g.get('Name')}'" for g in users[:5]) + "." + checks.append(_check(f"uet tag '{t.get('Name')}' ({t.get('Id')})", level, detail)) + + # 2. Goals + active_goals = [g for g in goals if g.get("Status") == "Active"] + if not active_goals: + checks.append(_check("conversion goals", "fail", + "No active conversion goal: Conversions stay 0 and conversion bidding has nothing to use.")) + for g in goals: + tracking = g.get("TrackingStatus") + level = { + "RecordingConversions": "pass", "NoRecentConversions": "warn", "TagUnverified": "fail", + "TagInactive": "fail", "InactiveDueToTagUnavailable": "fail", + }.get(tracking, "info") + if g.get("Status") != "Active": + level = "info" + detail = f"{g.get('Type')} goal, status {g.get('Status')}, tracking {tracking}" + if g.get("ExcludeFromBidding"): + detail += "; excluded from bidding (counts only in All conversions)" + if g.get("ConversionWindowInMinutes"): + detail += f"; {int(g['ConversionWindowInMinutes']) // 1440}-day window" + checks.append(_check(f"goal '{g.get('Name')}'", level, detail + ".")) + counted = [g for g in active_goals if not g.get("ExcludeFromBidding")] + if active_goals and not counted: + checks.append(_check("goals counted in Conversions", "fail", + "Every active goal is excluded from bidding, so the Conversions column stays 0.")) + + # 3. Campaign-level goals + goal_names = {str(g.get("Id")): g.get("Name") for g in goals} + for c in campaigns: + ids = [str(i) for i in c.get("GoalIds") or []] + if ids: + checks.append(_check( + f"campaign '{c.get('Name')}' goals", "info", + "Optimizes for its own goals: " + ", ".join(goal_names.get(i, i) for i in ids) + ".", + )) + + # 4. Clicks against conversions in the window + report = _report(config, meta, "CampaignPerformanceReportRequest", + ["CampaignName", "CampaignStatus", "Clicks", "Spend", "ConversionsQualified", + "AllConversionsQualified"], + start, end) + activity = [] + for r in report: + clicks = int(_num(r.get("Clicks")) or 0) + conversions = _num(r.get("ConversionsQualified")) or 0.0 + all_conversions = _num(r.get("AllConversionsQualified")) or 0.0 + activity.append({"campaign_name": r.get("CampaignName"), "campaign_status": r.get("CampaignStatus"), + "clicks": clicks, "spend": round(_num(r.get("Spend")) or 0.0, 2), + "conversions": conversions, "all_conversions": all_conversions}) + if clicks >= min_clicks and not all_conversions: + checks.append(_check( + f"campaign '{r.get('CampaignName')}' conversions", "warn", + f"{clicks} clicks and no conversion of any goal. Check the UET tag on the landing " + "pages and the goal's URL or event rule; phone calls are not counted unless call " + "tracking feeds Microsoft.", + )) + elif clicks and all_conversions and not conversions: + checks.append(_check( + f"campaign '{r.get('CampaignName')}' conversions", "warn", + f"{all_conversions:g} conversion(s) only in All conversions: the goals that fire are " + "excluded from bidding.", + )) + + order = {"fail": 0, "warn": 1, "info": 2, "pass": 3} + checks.sort(key=lambda c: order.get(c["status"], 4)) + verdict = ("broken" if any(c["status"] == "fail" for c in checks) + else "needs attention" if any(c["status"] == "warn" for c in checks) else "ok") + insights.append( + "A consent banner that blocks the UET tag hides conversions from people who decline; " + "Microsoft's numbers then run below real leads." + ) + return { + "ad_account_id": account, + "date_range": {"start": start.isoformat(), "end": end.isoformat()}, + "verdict": verdict, + "checks": checks, + "uet_tags": [{"tag_id": str(t.get("Id")), "name": t.get("Name"), "tracking_status": t.get("TrackingStatus")} + for t in tags if isinstance(t, dict)], + "goals": [ + {"goal_id": str(g.get("Id")), "name": g.get("Name"), "type": g.get("Type"), + "status": g.get("Status"), "tracking_status": g.get("TrackingStatus"), + "exclude_from_bidding": g.get("ExcludeFromBidding"), "count_type": g.get("CountType"), + "scope": g.get("Scope"), "tag_id": str(g.get("TagId") or "") or None} + for g in goals + ], + "campaign_activity": activity, + "insights": ([zone_note(meta["time_zone"])] if zone_note(meta["time_zone"]) else []) + insights, + } + + +# --------------------------------------------------------------------------- +# Location lookup (Microsoft's geographic location codes file) +# --------------------------------------------------------------------------- + +_GEO_CACHE: dict[str, Any] = {} + + +def _geo_cache_path(): + from pathlib import Path + + return Path("~/.adloop/cache/microsoft_geo_locations.csv").expanduser() + + +def _geo_column(headers: list[str], *needles: str) -> str | None: + lowered = {h: h.lower() for h in headers} + for needle in needles: + for header, low in lowered.items(): + if needle in low: + return header + return None + + +def load_geo_locations(config: AdLoopConfig, *, account: str = "", customer: str = "") -> list[dict]: + """Every Microsoft location (id, name, type, status), cached per file version. + + GeoLocationsFileUrl/Query returns a short-lived download link and the + file's last-modified time; the file is downloaded again only when it is + newer than the cached copy. + """ + import gzip + import json as _json + + info = campaign_request( + config, "GeoLocationsFileUrl/Query", + {"Version": "2.0", "LanguageLocale": "en", "CompressionType": "GZip"}, + account_id=account, customer_id=customer, + ) + modified = str(info.get("LastModifiedTimeUtc") or "") + if _GEO_CACHE.get("modified") == modified and _GEO_CACHE.get("rows"): + return _GEO_CACHE["rows"] + path = _geo_cache_path() + meta_path = path.with_suffix(".json") + data: bytes | None = None + try: + if path.exists() and meta_path.exists() and _json.loads(meta_path.read_text()).get("modified") == modified: + data = path.read_bytes() + except (OSError, ValueError): + data = None + if data is None: + url = info.get("FileUrl") + if not url: + raise _client_error("Microsoft returned no location file link.") + data = _client.download_file(url, what="location file") + if data[:2] == b"\x1f\x8b": + data = gzip.decompress(data) + try: + path.parent.mkdir(parents=True, exist_ok=True) + path.write_bytes(data) + meta_path.write_text(_json.dumps({"modified": modified})) + except OSError: + pass + rows = _client.parse_csv(data) + headers = list(rows[0]) if rows else [] + id_col = _geo_column(headers, "location id", "id") + name_col = _geo_column(headers, "display name", "name") + type_col = _geo_column(headers, "type") + status_col = _geo_column(headers, "status") + out = [ + { + "location_id": str(r.get(id_col) or "").strip(), + "name": r.get(name_col) or "", + "type": r.get(type_col) if type_col else None, + "status": r.get(status_col) if status_col else None, + } + for r in rows if id_col and str(r.get(id_col) or "").strip() + ] + _GEO_CACHE.update(modified=modified, rows=out) + return out + + +def _client_error(message: str): + from adloop.microsoft_ads.auth import MicrosoftAdsApiError + + return MicrosoftAdsApiError(message) + + +def location_names(rows: list[dict], ids: list[str]) -> dict[str, str]: + wanted = {str(i) for i in ids} + return {r["location_id"]: r["name"] for r in rows if r["location_id"] in wanted} + + +def search_microsoft_locations( + config: AdLoopConfig, *, ad_account_id: str = "", query: str = "", location_type: str = "", limit: int = 20, +) -> dict: + """Location ids (countries, states, metros, cities, postal codes) matching a name.""" + query = (query or "").strip().lower() + if not query: + raise ValueError("query is required, e.g. 'Chicago' or '60601'.") + meta = account_meta(config, ad_account_id) + rows = load_geo_locations(config, account=meta["ad_account_id"], customer=_customer(config, meta)) + kind = (location_type or "").strip().lower() + hits = [ + r for r in rows + if query in r["name"].lower() and (not kind or kind in str(r.get("type") or "").lower()) + ] + hits.sort(key=lambda r: (not r["name"].lower().startswith(query), "deprecat" in str(r.get("status") or "").lower(), len(r["name"]))) + limit = max(1, min(int(limit or 20), 100)) + return { + "query": query, + "locations": hits[:limit], + "total_matches": len(hits), + "note": ( + "Pass location_id values to update_microsoft_campaign_targeting or " + "draft_microsoft_campaign. Locations whose status is PendingDeprecation cannot be added." + ), + } diff --git a/src/adloop/microsoft_ads/write.py b/src/adloop/microsoft_ads/write.py new file mode 100644 index 00000000..525b29db --- /dev/null +++ b/src/adloop/microsoft_ads/write.py @@ -0,0 +1,347 @@ +"""Microsoft Advertising write tools — draft → preview → (dry run) → apply. + +Same gate as Google Ads and Reddit writes: a draft function validates the +request, runs the safety guards, stores a :class:`ChangePlan` and returns +its preview; ``confirm_and_apply`` recognises the ``microsoft_`` prefix and +hands the plan to :func:`preflight` (dry run) or :func:`apply_plan`. + +Microsoft's Campaign Management API has no validate-only mode, so the dry +run is a read-side preflight: it re-reads the target, confirms it still +exists in the state the preview showed, and re-runs the budget cap. Nothing +is sent. The real apply runs the same preflight first, so a change made in +Microsoft Advertising between the preview (or the dry run) and the apply is +refused instead of overwritten. Updates send only the fields that change; +Microsoft leaves every field it does not receive as it was. +""" + +from __future__ import annotations + +from typing import TYPE_CHECKING, Any + +from adloop.microsoft_ads.auth import MicrosoftAdsApiError +from adloop.microsoft_ads.client import campaign_request, fault_details +from adloop.microsoft_ads.read import ( + _ad_groups, + _ads, + _campaigns, + _customer, + _keywords, + _money, + account_meta, +) + +if TYPE_CHECKING: + from adloop.config import AdLoopConfig + from adloop.safety.preview import ChangePlan + +PLATFORM = "microsoft" +OPERATION_PREFIX = "microsoft_" +ENTITY_TYPES = ("campaign", "ad_group", "keyword", "ad") +_STATUS = {"pause": "Paused", "enable": "Active"} + + +def _validation_error(details: list[str]) -> dict: + return {"error": "Validation failed", "details": details} + + +def _guard(operation: str, config: AdLoopConfig) -> dict | None: + from adloop.safety.guards import SafetyViolation, check_blocked_operation + + try: + check_blocked_operation(operation, config.safety) + except SafetyViolation as e: + return {"error": str(e)} + return None + + +def _store(plan_kwargs: dict, *, warnings: list[str] | None = None) -> dict: + from adloop.safety.preview import ChangePlan, store_plan + + plan = ChangePlan(platform=PLATFORM, **plan_kwargs) + store_plan(plan) + preview = plan.to_preview() + if warnings: + preview["warnings"] = warnings + return preview + + +def find_entity( + config: AdLoopConfig, account: str, customer: str, entity_type: str, entity_id: str, + *, parent_id: str = "", +) -> dict | None: + """Locate an entity and its parents; ad groups, keywords and ads carry no parent id.""" + entity_id = str(entity_id) + for c in _campaigns(config, account, customer): + cid = str(c.get("Id")) + if entity_type == "campaign": + if cid == entity_id: + return {"entity": c, "campaign": c} + continue + if entity_type == "ad_group" and parent_id and cid != str(parent_id): + continue + for g in _ad_groups(config, account, customer, cid): + gid = str(g.get("Id")) + if entity_type == "ad_group": + if gid == entity_id: + return {"entity": g, "campaign": c, "ad_group": g} + continue + if parent_id and gid != str(parent_id): + continue + children = (_keywords if entity_type == "keyword" else _ads)(config, account, customer, gid) + for child in children: + if str(child.get("Id")) == entity_id: + return {"entity": child, "campaign": c, "ad_group": g} + return None + + +def _label(found: dict, entity_type: str) -> str: + entity = found["entity"] + if entity_type == "keyword": + return f"{entity.get('Text')} [{entity.get('MatchType')}]" + if entity_type == "ad": + return f"{entity.get('Type')} ad {entity.get('Id')}" + return str(entity.get("Name")) + + +def draft_microsoft_status( + config: AdLoopConfig, + *, + action: str, + ad_account_id: str = "", + entity_type: str = "", + entity_id: str = "", + parent_id: str = "", +) -> dict: + """Draft pausing or enabling a campaign, ad group, keyword or ad.""" + operation = "microsoft_set_status" + blocked = _guard(operation, config) + if blocked: + return blocked + entity_type = (entity_type or "").strip().lower() + entity_id = str(entity_id or "").strip() + errors = [] + if entity_type not in ENTITY_TYPES: + errors.append(f"entity_type must be one of {list(ENTITY_TYPES)}, got '{entity_type}'") + if not entity_id: + errors.append("entity_id is required") + if errors: + return _validation_error(errors) + meta = account_meta(config, ad_account_id) + account, customer = meta["ad_account_id"], _customer(config, meta) + found = find_entity(config, account, customer, entity_type, entity_id, parent_id=parent_id) + if not found: + return {"error": f"Microsoft {entity_type.replace('_', ' ')} '{entity_id}' was not found in account {account}."} + + target = _STATUS[action] + entity = found["entity"] + current = entity.get("Status") + warnings = [] + if current == target: + warnings.append(f"It is already {target}; applying changes nothing.") + if target == "Active": + for level in ("campaign", "ad_group"): + parent = found.get(level) + if parent is not None and parent is not entity and parent.get("Status") != "Active": + warnings.append( + f"Its {level.replace('_', ' ')} '{parent.get('Name')}' is {parent.get('Status')}, " + "so it still will not serve." + ) + if entity.get("EditorialStatus") in ("Disapproved", "Inactive"): + warnings.append(f"Editorial status is {entity.get('EditorialStatus')}: it will not serve until fixed.") + if target == "Paused" and entity_type == "campaign": + warnings.append("Pausing the campaign stops every ad in it.") + + changes = { + "ad_account_id": account, + "customer_id": customer, + "name": _label(found, entity_type), + "entity_name": _label(found, entity_type), + "campaign_id": str(found["campaign"].get("Id")), + "campaign_name": found["campaign"].get("Name"), + "ad_group_id": str(found["ad_group"].get("Id")) if found.get("ad_group") else None, + "ad_group_name": found["ad_group"].get("Name") if found.get("ad_group") else None, + "ad_type": entity.get("Type") if entity_type == "ad" else None, + "current_status": current, + "target_status": target, + } + return _store( + {"operation": operation, "entity_type": entity_type, "entity_id": entity_id, + "customer_id": account, "changes": changes}, + warnings=warnings, + ) + + +def draft_microsoft_campaign_budget( + config: AdLoopConfig, *, ad_account_id: str = "", campaign_id: str = "", daily_budget: float = 0.0, +) -> dict: + """Draft a new daily budget for one campaign (its own budget, not a shared one).""" + from adloop.safety.guards import SafetyViolation, check_budget_cap + + operation = "microsoft_update_campaign_budget" + blocked = _guard(operation, config) + if blocked: + return blocked + errors = [] + campaign_id = str(campaign_id or "").strip() + if not campaign_id: + errors.append("campaign_id is required") + try: + amount = round(float(daily_budget), 2) + except (TypeError, ValueError): + amount = 0.0 + if amount <= 0: + errors.append("daily_budget must be a positive amount in the account currency") + if errors: + return _validation_error(errors) + try: + check_budget_cap(amount, config.safety) + except SafetyViolation as e: + return {"error": str(e)} + + meta = account_meta(config, ad_account_id) + account, customer = meta["ad_account_id"], _customer(config, meta) + found = find_entity(config, account, customer, "campaign", campaign_id) + if not found: + return {"error": f"Microsoft campaign '{campaign_id}' was not found in account {account}."} + campaign = found["entity"] + budget_id = campaign.get("BudgetId") + if budget_id and str(budget_id) not in ("0", "None"): + return { + "error": ( + f"Campaign '{campaign.get('Name')}' uses shared budget {budget_id}; its daily amount " + "is set on that budget and changing it changes every campaign sharing it. Change " + "it in Microsoft Advertising (Shared library → Budgets)." + ) + } + current = _money(campaign.get("DailyBudget")) + warnings = [] + if current is not None and current == amount: + warnings.append("The budget is already this amount; applying changes nothing.") + if current and amount > current * 2: + warnings.append(f"This more than doubles the budget ({current} → {amount} {meta['currency']}).") + warnings.append( + f"Microsoft can spend up to 30.4 × the daily budget in a month: about " + f"{round(amount * 30.4, 2)} {meta['currency']}." + ) + return _store( + { + "operation": operation, + "entity_type": "campaign", + "entity_id": campaign_id, + "customer_id": account, + "changes": { + "ad_account_id": account, + "customer_id": customer, + "entity_name": campaign.get("Name"), + "campaign_name": campaign.get("Name"), + "campaign_status": campaign.get("Status"), + "current_daily_budget": current, + "new_daily_budget": amount, + "currency": meta["currency"], + }, + }, + warnings=warnings, + ) + + +def is_microsoft_plan(plan: ChangePlan) -> bool: + return str(plan.operation or "").startswith(OPERATION_PREFIX) + + +def preflight(config: AdLoopConfig, plan: ChangePlan) -> dict: + """Re-read the target and re-check the gates; sends nothing.""" + from adloop.microsoft_ads import manage + from adloop.safety.guards import check_budget_cap + + if plan.operation in manage.OPERATIONS: + return manage.preflight(config, plan) + changes = plan.changes or {} + account = changes.get("ad_account_id") or plan.customer_id + customer = changes.get("customer_id") or "" + parent = changes.get("ad_group_id") if plan.entity_type in ("keyword", "ad") else "" + found = find_entity(config, account, customer, plan.entity_type, plan.entity_id, parent_id=parent or "") + if not found: + raise ValueError(f"{plan.entity_type} '{plan.entity_id}' no longer exists.") + entity = found["entity"] + checks: dict[str, Any] = {"ad_account_id": account, "entity": changes.get("name") or entity.get("Name")} + if plan.operation == "microsoft_set_status": + now = entity.get("Status") + if now != changes.get("current_status"): + raise ValueError( + f"The status changed since the draft ({changes.get('current_status')} → {now}); redraft." + ) + checks["status_now"] = now + checks["already_in_target_status"] = now == changes.get("target_status") + elif plan.operation == "microsoft_update_campaign_budget": + budget_id = entity.get("BudgetId") + if budget_id and str(budget_id) not in ("0", "None"): + raise ValueError("The campaign moved to a shared budget since the draft; redraft.") + now = _money(entity.get("DailyBudget")) + if now != changes.get("current_daily_budget"): + raise ValueError( + f"The budget changed since the draft ({changes.get('current_daily_budget')} → {now}); redraft." + ) + check_budget_cap(float(changes["new_daily_budget"]), config.safety) + checks["budget_now"] = now + checks["budget_cap_ok"] = True + else: + raise ValueError(f"Unknown Microsoft operation: {plan.operation}") + return checks + + +def _raise_partial(payload: dict, what: str) -> None: + partial = [e for e in payload.get("PartialErrors") or [] if e] + if partial: + _codes, message, _tracking = fault_details({"PartialErrors": partial}) + raise MicrosoftAdsApiError(f"Microsoft refused the {what}: {message or partial}") + + +def apply_plan(config: AdLoopConfig, plan: ChangePlan) -> dict: + """Execute a Microsoft plan. Called by ``confirm_and_apply`` after the gate. + + Re-runs :func:`preflight` first: a dry run can be minutes or hours old, + and the plan must still describe the live entity when it is applied. + """ + from adloop.microsoft_ads import manage + + preflight(config, plan) + if plan.operation in manage.OPERATIONS: + return manage.apply_plan(config, plan) + changes = plan.changes or {} + account = changes.get("ad_account_id") or plan.customer_id + customer = changes.get("customer_id") or "" + kwargs = {"account_id": account, "customer_id": customer, "method": "PUT", "mutation": True} + + if plan.operation == "microsoft_update_campaign_budget": + payload = campaign_request( + config, "Campaigns", + {"AccountId": account, + "Campaigns": [{"Id": plan.entity_id, "DailyBudget": changes["new_daily_budget"]}]}, + **kwargs, + ) + _raise_partial(payload, "budget change") + return {"entity_type": "campaign", "entity_id": plan.entity_id, + "campaign_name": changes.get("campaign_name"), + "daily_budget": changes["new_daily_budget"], "currency": changes.get("currency")} + + if plan.operation == "microsoft_set_status": + status = changes["target_status"] + etype, eid = plan.entity_type, plan.entity_id + if etype == "campaign": + body = {"AccountId": account, "Campaigns": [{"Id": eid, "Status": status}]} + path = "Campaigns" + elif etype == "ad_group": + body = {"CampaignId": changes["campaign_id"], "AdGroups": [{"Id": eid, "Status": status}]} + path = "AdGroups" + elif etype == "keyword": + body = {"AdGroupId": changes["ad_group_id"], "Keywords": [{"Id": eid, "Status": status}]} + path = "Keywords" + else: + body = {"AdGroupId": changes["ad_group_id"], + "Ads": [{"Id": eid, "Status": status, "Type": changes.get("ad_type")}]} + path = "Ads" + payload = campaign_request(config, path, body, **kwargs) + _raise_partial(payload, "status change") + return {"entity_type": etype, "entity_id": eid, "name": changes.get("name"), "status": status} + + raise ValueError(f"Unknown Microsoft operation: {plan.operation}") diff --git a/src/adloop/oauth_redirect.py b/src/adloop/oauth_redirect.py new file mode 100644 index 00000000..6fbc6a00 --- /dev/null +++ b/src/adloop/oauth_redirect.py @@ -0,0 +1,135 @@ +"""One-shot localhost listener for OAuth redirects (sign-in commands). + +``adloop microsoft-login`` opens the provider's sign-in page in the +browser; the provider then redirects to +``http://localhost:/?code=...&state=...``. This serves that one +request and returns its query parameters. + +Hardened against a stuck sign-in: the overall deadline uses a monotonic +clock, and every socket read is bounded, so an accepted connection that +never sends a request cannot hold the command open. +""" + +from __future__ import annotations + +import time +from urllib.parse import parse_qsl, urlsplit + + +class RedirectTimeout(Exception): + """No redirect arrived before the deadline.""" + + +# How long one connection may take to send its request. A client that +# trickles bytes is cut off here, so a real redirect waiting behind it is +# still served before the sign-in deadline. +_PER_CONNECTION_SECONDS = 5.0 + + +class _DeadlineReader: + """The request side of a connection, with an absolute deadline. + + A per-read socket timeout alone can be outlasted by a peer that sends a + byte just before each read times out; this bounds the whole request. + """ + + def __init__(self, sock, deadline: float): + self._sock = sock + self._deadline = deadline + self._buffer = b"" + + def _fill(self) -> bool: + remaining = self._deadline - time.monotonic() + if remaining <= 0: + raise TimeoutError("the request took too long") + self._sock.settimeout(remaining) + chunk = self._sock.recv(4096) + if not chunk: + return False + self._buffer += chunk + return True + + def readline(self, limit: int = -1) -> bytes: + while b"\n" not in self._buffer and (limit < 0 or len(self._buffer) < limit): + if not self._fill(): + break + end = self._buffer.find(b"\n") + size = end + 1 if end >= 0 else len(self._buffer) + if limit >= 0: + size = min(size, limit) + line, self._buffer = self._buffer[:size], self._buffer[size:] + return line + + def read(self, size: int = -1) -> bytes: + while (size < 0 or len(self._buffer) < size) and self._fill(): + pass + size = len(self._buffer) if size < 0 else size + data, self._buffer = self._buffer[:size], self._buffer[size:] + return data + + def close(self) -> None: + return None + + +def is_local_redirect(redirect_uri: str) -> bool: + parts = urlsplit(redirect_uri) + return parts.scheme == "http" and parts.hostname in ("localhost", "127.0.0.1") + + +def listen_once(redirect_uri: str, timeout: float, *, provider: str = "the") -> dict: + """Serve the redirect URI on localhost until the browser arrives; return its query.""" + from http.server import BaseHTTPRequestHandler, HTTPServer + + parts = urlsplit(redirect_uri) + expected_path = parts.path or "/" + captured: dict = {} + page = ( + "

AdLoop received the " + f"{provider} sign-in.

You can close this tab and return to the terminal.

" + ).encode() + + class Handler(BaseHTTPRequestHandler): + def setup(self): + super().setup() + # The whole request must arrive within the connection's budget + # and the sign-in deadline, however slowly it trickles in. + self.rfile = _DeadlineReader( + self.connection, min(deadline, time.monotonic() + _PER_CONNECTION_SECONDS)) + + def do_GET(self): # noqa: N802 (http.server naming) + here = urlsplit(self.path) + if (here.path or "/") != expected_path: + self.send_response(404) + self.end_headers() + return + captured.update(dict(parse_qsl(here.query))) + self.send_response(200) + self.send_header("Content-Type", "text/html; charset=utf-8") + self.end_headers() + self.wfile.write(page) + + def log_message(self, *_args): + return + + # An accepted connection that never sends a request must not hold the + # sign-in past its deadline: every socket read is bounded too. + Handler.timeout = max(0.1, min(5.0, timeout)) + + class Server(HTTPServer): + def handle_error(self, request, client_address): # noqa: D401 — silence timeouts + return + + server = Server((parts.hostname or "127.0.0.1", parts.port or 80), Handler) + deadline = time.monotonic() + timeout + try: + while not captured: + remaining = deadline - time.monotonic() + if remaining <= 0: + break + server.timeout = min(1.0, remaining) + server.handle_request() + finally: + server.server_close() + if not captured: + raise RedirectTimeout("No sign-in arrived before the timeout.") + return captured diff --git a/src/adloop/rules/adloop.md b/src/adloop/rules/adloop.md index 5a696608..3f0adc6b 100644 --- a/src/adloop/rules/adloop.md +++ b/src/adloop/rules/adloop.md @@ -12,7 +12,7 @@ You have access to AdLoop MCP tools that connect Google Ads, Reddit Ads and Goog | Tool | When to Use | Key Parameters | |------|-------------|----------------| -| `health_check` | First thing to run when tools are failing — tests OAuth token, GA4, Ads, and (when configured) Reddit Ads connectivity | (none) | +| `health_check` | First thing to run when tools are failing — tests OAuth token, GA4, Ads, and (when configured) Reddit Ads and Microsoft Advertising connectivity | (none) | **A tool you expect is missing?** Apps such as claude.ai, ChatGPT and Perplexity cache AdLoop's tool list from when the connection was made. `health_check` returns `adloop_version` and `tools_offered`, the tools this server offers to you. If the user asks for something a tool in `tools_offered` does and that tool isn't in your own tool list, don't improvise with other tools: tell the user their app shows an older list and to refresh the AdLoop connection (claude.ai: Settings → Connectors → AdLoop; ChatGPT: the AdLoop plugin's settings; Perplexity: remove and add the connector again; coding agents: reconnect the MCP server or start a new session). @@ -265,6 +265,50 @@ Reddit is a second ad platform with its own connection (own OAuth app, no develo 4. Cross-check `get_reddit_ads` for `REJECTED` ads (`rejection_reason`) and `PENDING_APPROVAL` — they explain missing spend 5. Present spend, clicks, CTR, CPC, conversions, CPA in account currency; compare against Google Ads only on CPA/ROAS, never on CTR (feed placements behave differently from search) +### Microsoft Advertising Tools + +Microsoft Advertising (Bing, Yahoo, AOL, DuckDuckGo search ads) through the REST API v13. Toolset `microsoft_ads`; needs `microsoft_ads.developer_token`, `microsoft_ads.client_id` (an Entra app with public client flows and the msads.manage permission) and a one-time `adloop microsoft-login` (browser sign-in on `http://localhost:8080/callback`; sign in with the user that has access to the ad accounts. Directories with security defaults block the device-code flow with sign-in error 530035, so `--device-code` is only a fallback). `customer_id` is the manager account, `ad_account_id` the default ad account; `list_microsoft_ads_accounts` shows both. + +| Tool | When to Use | Key Parameters | +|------|-------------|----------------| +| `list_microsoft_ads_accounts` | Discovery: the signed-in user, manager accounts, ad accounts (id, number, currency, time zone, status) | (none) | +| `get_microsoft_campaigns` | Budget (own or shared), bidding, languages, included/excluded locations and location intent | `include_targeting` | +| `get_microsoft_ad_groups` | Bid, network (search partners on/off), Audience Network exposure, dates, campaign status | `campaign_id` | +| `get_microsoft_keywords` | Match type, bid, status, editorial review, parent statuses | `campaign_id`, `ad_group_id` | +| `get_microsoft_ads` | Headlines (pins), descriptions, paths, final URLs, editorial review | `campaign_id`, `ad_group_id` | +| `get_microsoft_performance` | Spend, clicks, CTR, CPC, conversions, CPA, revenue, impression share and share lost to budget/rank | `level` (account/campaign/ad_group/keyword/ad), date range, `breakdown` (date/device), `campaign_id`, `compact` | +| `get_microsoft_search_terms` | What people searched, the keyword and match type it matched, waste candidates | date range, `campaign_id`, `min_clicks`, `compact` | +| `get_microsoft_location_performance` | Where clicks came from; people physically there vs searching about the place | date range, `group_by` (city/metro/state/postal_code/most_specific) | +| `get_microsoft_conversion_setup` | Audit: UET tag status, conversion goals (tracking status, excluded from bidding), campaign goals, clicks without conversions | date range, `min_clicks` | +| `update_microsoft_campaign_budget` | Draft a new daily budget (own budget only; capped by `max_daily_budget`) | `campaign_id`, `daily_budget` | +| `pause_microsoft_entity` / `enable_microsoft_entity` | Draft pausing or enabling a campaign, ad group, keyword or ad | `entity_type`, `entity_id`, `parent_id` (optional) | +| `search_microsoft_locations` | Location ids (country, state, metro, city, postal code) by name; Microsoft's file is cached | `query`, `location_type` | +| `update_microsoft_campaign` | Name, bid strategy (ManualCpc, EnhancedCpc, MaxClicks, MaxConversions + target CPA), tracking template, final URL suffix | `campaign_id` + fields | +| `update_microsoft_campaign_targeting` | Included / excluded locations (full lists), location intent, ad schedule (replaces; account time zone, or the searcher's when the campaign uses AdScheduleUseSearcherTimeZone: the preview's `hours_in` says which) | `campaign_id`, `location_ids`, `excluded_location_ids`, `location_intent`, `ad_schedule` | +| `draft_microsoft_campaign` | New Search campaign, paused, with budget, bidding, languages, locations, intent | `name`, `daily_budget`, `languages`, `location_ids` | +| `draft_microsoft_ad_group` / `update_microsoft_ad_group` | New ad group (with keywords) / name, default bid, network, Audience Network adjustment | `campaign_id` or `ad_group_id` + fields | +| `draft_microsoft_keywords` / `update_microsoft_keyword_bids` | Add keywords (duplicates skipped) / change keyword bids | `ad_group_id`, `keywords` or `bids` | +| `get_microsoft_negative_keywords` | Direct negatives and shared lists with items, attachments and `remove_id`s | `campaign_id` | +| `propose_microsoft_negative_keyword_list` / `add_to_microsoft_negative_keyword_list` | New shared list (attached) / append to a list | `list_name` or `list_id`, `keywords`, `campaign_ids` | +| `attach_microsoft_negative_keyword_list` / `detach_microsoft_negative_keyword_list` | Link or unlink a list and campaigns | `list_id`, `campaign_ids` | +| `add_microsoft_negative_keywords` | Negatives directly on a campaign or ad group | `campaign_id` or `ad_group_id`, `keywords` | +| `draft_microsoft_responsive_search_ad` / `update_microsoft_responsive_search_ad` | New RSA (paused) / replace headlines, descriptions, URL, paths | `ad_group_id` or `ad_id` + copy | +| `get_microsoft_ad_extensions` | Sitelinks, callouts, snippets, call and image extensions per ad group, campaign and account, with `remove_id`s (image rows add `alt_text`, `display_text`, `layouts`, `media_ids` and `images` with each picture's size and `url`, to look at a photo before unlinking it) | `campaign_id` | +| `draft_microsoft_sitelinks` / `draft_microsoft_callouts` / `draft_microsoft_structured_snippet` / `draft_microsoft_call_extension` | Create and link extensions to a campaign (or the account) | `campaign_id` or `scope="account"` + content | +| `draft_microsoft_image_extension` | Photos with the search ads: uploads up to 10 images to the media library, creates one image extension per image and links them | `campaign_id`, `ad_group_id` or `scope="account"`; `image_paths` / `image_urls` / `upload_ids`; `alt_text` (required, ≤35); optional `display_text` (≤35), `final_url` | +| `remove_microsoft_entity` | Delete (irreversible, double confirmation): campaign, ad group, ad, keyword, or by `remove_id` a negative, list item, criterion, extension link (account, campaign or ad group; unlinking keeps the extension) | `entity_type`, `entity_id` | + +- **Statuses at every level.** Keyword and ad rows carry the ad group and campaign status; reports carry `campaign_status`, `ad_group_status`, `keyword_status`. An account whose status is not Active serves nothing; `BudgetPaused` campaigns stopped on budget. +- **Location intent matters for local businesses.** `PeopleInOrSearchingForOrViewingPages` (Microsoft's default) also reaches people elsewhere searching about the area. `get_microsoft_location_performance` shows how much spend that "location of interest" traffic took. +- **Monthly spend:** Microsoft may spend up to 30.4 × the daily budget in a month; the budget preview says so. +- **Writes** go through draft → preview → `confirm_and_apply`. Microsoft has no validate-only mode: the dry run re-reads the target, refuses if the budget or status changed since the draft or the campaign moved to a shared budget, and re-checks the cap. The real apply runs the same checks again right before sending, so a change made in Microsoft Advertising in between is refused, not overwritten: draft again. Updates send only the changed field. +- **Management rules** mirror Google Ads: broad match is refused on ManualCpc / EnhancedCpc campaigns, moving to manual bidding is refused while active broad keywords exist, new campaigns need languages and locations (default PeopleIn), new RSAs and campaigns are paused, while new keywords and ad groups are created Active as in Google Ads (the preview's `status_on_create` says so, and keywords in a live ad group serve as soon as they are applied), keyword and ad group bid raises are capped by `max_bid_increase_pct` (including a keyword falling back to the ad group bid), a first ad schedule needs a double confirmation. Replacing a schedule window deletes the old window before adding the new one when they overlap; the preview warns when that leaves the campaign briefly unscheduled. Negative keywords go in shared lists by default; every negative draft names active keywords it would block. +- **Multi-step applies** (a campaign then its targeting, a list then its attachments, extensions then their links) end with `PARTIAL_APPLY` when a later step fails, or when Microsoft creates some items of a batch and refuses others: `created` lists the IDs that exist, and the plan is retired so nothing is created twice. Check the account, then draft only what is missing. +- **Image extensions** (`draft_microsoft_image_extension`): JPEG, PNG or non-animated GIF, at most 5 MB, **1.91:1** (e.g. 1200x628), at least 703x368, at most 2592 wide and 2048 high; the draft refuses anything else and says how to crop it. Ask the user for alt text that describes the photo. Microsoft's help allows 25 image extensions per account, campaign or ad group, its API reference says 6: the draft warns above 6 and refuses above 25. `display_text` adds the multi-image layout, which needs at least five images in four extensions. **Caution:** image extensions can take search ads beyond Bing results: Microsoft's audience ads guide says search ads are extended to native placements on the Microsoft Audience Network (Outlook, MSN) with their image extensions, so check the ad groups' Audience Network setting with `get_microsoft_ad_groups` when the client wants search only. Images without a public URL go through `upload_images` first. +- Reports are built asynchronously and take a few seconds; long date ranges at keyword or search-term level take longer. +- Search terms with clicks and no conversions are candidates, not verdicts: calls from Microsoft ads convert outside its view unless call tracking feeds back. +- **Conversions** come from Microsoft's `ConversionsQualified` columns (the old `Conversions` columns are deprecated and read 0 in keyword and search-term reports); conversion rate and CPA are computed from them. A UET tag is required only by URL, duration, pages-per-visit and event goals: offline-import goals need none, and an unverified tag that no active goal uses is a loose end (warn), not a broken setup. + ### When user asks about organic traffic, SEO, or paid/organic overlap 1. Call `list_gsc_sites` if no site is configured; confirm the property with the user @@ -293,7 +337,7 @@ For images that have no public URL: a file on the user's computer, or an image t - **With the card** (`upload: "card"` in the result): the user drops PNG, JPEG or GIF files (up to 5 MB) on the card; it then posts the upload ids into the chat. Wait for that message instead of asking for a URL. - **With an upload link** (`upload_url`): give the user the link (valid 30 minutes) to open in the browser, then call `list_uploads` once they say they are done. A coding agent that has the file on disk can upload it itself: `curl -T "logo.png" "/"`, one call per file. -- **Using an upload:** `draft_image_assets(upload_ids=["up_..."])` for Google Ads; `"upload:up_..."` as `image_url`, `thumbnail_url` or a carousel card's `image_url` in `draft_reddit_ad` (AdLoop Cloud only, because Reddit downloads the image from a short-lived public link). Videos cannot be uploaded. +- **Using an upload:** `draft_image_assets(upload_ids=["up_..."])` for Google Ads; `draft_microsoft_image_extension(upload_ids=["up_..."])` for Microsoft Advertising; `"upload:up_..."` as `image_url`, `thumbnail_url` or a carousel card's `image_url` in `draft_reddit_ad` (AdLoop Cloud only, because Reddit downloads the image from a short-lived public link). Videos cannot be uploaded. - Uploads expire after 24 hours. Self-hosted without a card, pass local files directly (`image_paths`). ### Offline Conversion Uploads diff --git a/src/adloop/server.py b/src/adloop/server.py index 4a36b51b..20fb0440 100644 --- a/src/adloop/server.py +++ b/src/adloop/server.py @@ -46,6 +46,7 @@ "web": "PageSpeed / web performance", "merchant": "Merchant Center reads", "reddit": "Reddit Ads reads, writes, and planning", + "microsoft_ads": "Microsoft Advertising (Bing) reads and campaign management", } # Finer selections inside "ads" (issue #56): every ads tool also carries @@ -366,6 +367,7 @@ def set_request_state_keys(keys: list[bytes]) -> None: "web": "PageSpeed Insights API: https://developers.google.com/speed/docs/insights/v5/about", "merchant": "Merchant API: https://developers.google.com/merchant/api/overview", "reddit": "Reddit Ads API: https://ads-api.reddit.com/docs/v3/", + "microsoft_ads": "Microsoft Advertising API: https://learn.microsoft.com/advertising/guides/", # health_check and confirm_and_apply act on whichever platform is set up. "core": ( "Google Ads API: https://developers.google.com/google-ads/api/docs/start, " @@ -519,12 +521,58 @@ def _reddit_structured_error(exc: Exception) -> dict | None: return None +def _microsoft_ads_structured_error(exc: Exception) -> dict | None: + """Microsoft Advertising translations, keyed on exception type.""" + from adloop.microsoft_ads.auth import MicrosoftAdsApiError, MicrosoftAdsAuthError + + if isinstance(exc, MicrosoftAdsAuthError): + hints = { + "missing_developer_token": ( + "Request a developer token in Microsoft Advertising (Settings → Developer " + "settings, or https://developers.ads.microsoft.com/Account) and set " + "microsoft_ads.developer_token." + ), + "missing_client": "Set microsoft_ads.client_id to the Entra app id, then run `adloop microsoft-login`.", + } + return { + "error": str(exc), + "hint": hints.get( + exc.error_code, + "Run `adloop microsoft-login` and sign in with the account that has access " + "to the Microsoft Advertising accounts, then restart the MCP server.", + ), + "auth_error": "MICROSOFT_ADS_" + (exc.error_code or "auth").upper(), + } + if isinstance(exc, MicrosoftAdsApiError): + if exc.status == 429: + return { + "error": str(exc), + "hint": "Wait for the reset before calling again; do not retry in a loop.", + "auth_error": "MICROSOFT_ADS_RATE_LIMITED", + "retry_after": exc.retry_after, + } + result = {"error": str(exc), "microsoft_ads_codes": exc.codes or None} + if exc.tracking_id: + result["tracking_id"] = exc.tracking_id + if set(exc.codes) & {"106", "UserIsNotAuthorized", "1102", "CampaignServiceInvalidAccountId"}: + result["hint"] = ( + "The signed-in user has no access to this account, or the account or customer id " + "is wrong. Check list_microsoft_ads_accounts." + ) + return result + return None + + def _structured_error(fn_name: str, exc: Exception) -> dict: """Translate common auth failures into actionable structured errors.""" reddit = _reddit_structured_error(exc) if reddit is not None: reddit.setdefault("tool", fn_name) return reddit + microsoft = _microsoft_ads_structured_error(exc) + if microsoft is not None: + microsoft.setdefault("tool", fn_name) + return microsoft err = str(exc) err_lower = err.lower() @@ -675,7 +723,7 @@ def wrapper(*args, **kwargs): @_safe def health_check() -> dict: """Test AdLoop connectivity — checks OAuth token, GA4 API, Google Ads API, - and (when configured) the Reddit Ads API. + and (when configured) the Reddit Ads and Microsoft Advertising APIs. Returns the status of each service and actionable guidance when something is broken, which makes it the diagnostic for failures in other tools. @@ -786,6 +834,36 @@ def _ga4_failed(surface: str, e: Exception) -> None: else: status["reddit"] = "not_configured" + ms_cfg = current_config().microsoft_ads + if _microsoft_ads_configured(): + try: + from adloop.microsoft_ads.read import account_meta as ms_account_meta + + if ms_cfg.ad_account_id: + meta = ms_account_meta(current_config(), "", fresh=True) + status["microsoft_ads"] = "ok" + status["microsoft_ads_account"] = meta["ad_account_id"] + status["microsoft_ads_account_name"] = meta["name"] + status["microsoft_ads_account_status"] = meta["status"] + else: + from adloop.microsoft_ads.client import ms_request + + ms_request(current_config(), "customer", "User/Query", {"UserId": None}) + status["microsoft_ads"] = "ok" + status["microsoft_ads_note"] = ( + "Signed in; set microsoft_ads.ad_account_id (see list_microsoft_ads_accounts)." + ) + except Exception as e: + parsed = _structured_error("health_check", e) + status["microsoft_ads"] = "error" + status["microsoft_ads_error"] = parsed["error"] + if "hint" in parsed: + status["microsoft_ads_hint"] = parsed["hint"] + if "auth_error" in parsed: + status["microsoft_ads_auth_error"] = parsed["auth_error"] + else: + status["microsoft_ads"] = "not_configured" + if status["ga4"] == "error" or status["ads"] == "error": if status.get("ads_hint"): status["hint"] = status["ads_hint"] @@ -5771,7 +5849,8 @@ def approve_change( # --------------------------------------------------------------------------- # Images without a public URL reach AdLoop through the upload card (apps with # MCP Apps) or an upload link (hosted, every other app). Tools then take the -# upload id: draft_image_assets(upload_ids=...), upload: for Reddit. +# upload id: draft_image_assets(upload_ids=...), draft_microsoft_image_extension(upload_ids=...), +# upload: for Reddit. @_tool( @@ -5895,6 +5974,7 @@ def list_uploads() -> dict: "uploads": uploads, "usage": ( "draft_image_assets(upload_ids=[...]) for Google Ads; " + "draft_microsoft_image_extension(upload_ids=[...]) for Microsoft Advertising; " "\"upload:\" as image_url, thumbnail_url or a carousel card's " "image_url in draft_reddit_ad (AdLoop Cloud only). CSV uploads: upload_id in " "draft_upload_call_conversions or draft_upload_enhanced_conversions_for_leads." @@ -7132,6 +7212,938 @@ def draft_reddit_ad( ) +# --------------------------------------------------------------------------- +# Microsoft Advertising Tools +# --------------------------------------------------------------------------- +# Another ad platform (REST API v13). ``ad_account_id`` falls back to +# microsoft_ads.ad_account_id; the CustomerId header comes from +# microsoft_ads.customer_id or the account's manager. + + +def _microsoft_ads_configured() -> bool: + """Set up here: hosted, the credentials provider must support Microsoft; + self-hosted, the config names a developer token or an app.""" + from adloop.auth import get_credentials_provider + from adloop.runtime import deployment_mode + + if deployment_mode() == "server": + return hasattr(get_credentials_provider(), "microsoft_ads_credentials") + cfg = current_config().microsoft_ads + return bool(cfg.developer_token or cfg.client_id) + + + +@_tool(title="List Microsoft Advertising accounts", annotations=_READONLY, tags={"microsoft_ads"}) +@_safe +def list_microsoft_ads_accounts() -> dict: + """List the Microsoft Advertising (Bing) ad accounts the signed-in user can reach. + + Returns the user, their customers (manager accounts) with roles, and per + ad account the ad_account_id, customer_id, name, number, currency, time + zone and status that the other Microsoft tools take. + """ + from adloop.microsoft_ads.read import list_microsoft_ads_accounts as _impl + + return _impl(current_config()) + + +@_tool(title="Microsoft Advertising campaigns", annotations=_READONLY, tags={"microsoft_ads"}) +@_safe +def get_microsoft_campaigns(ad_account_id: str = "", include_targeting: bool = True) -> dict: + """List Microsoft Advertising campaigns with status, daily budget, bidding, languages and location targeting. + + Location targeting lists the included and excluded locations and the + location intent (people in the area, or also people searching about it). + Insights flag an inactive account, budget-paused or suspended campaigns, + campaigns without locations, intent that reaches beyond the area, and + shared budgets. + + Args: + ad_account_id: Microsoft ad account id (from list_microsoft_ads_accounts). + Empty uses microsoft_ads.ad_account_id from the config. + include_targeting: Read each campaign's location criteria (three + calls per campaign); default true. + """ + from adloop.microsoft_ads.read import get_microsoft_campaigns as _impl + + return _impl(current_config(), ad_account_id=ad_account_id, include_targeting=include_targeting) + + +@_tool(title="Microsoft Advertising ad groups", annotations=_READONLY, tags={"microsoft_ads"}) +@_safe +def get_microsoft_ad_groups(ad_account_id: str = "", campaign_id: str = "") -> dict: + """List Microsoft Advertising ad groups with bid, network, language, dates and campaign status. + + Insights flag ad groups that also run on syndicated search partners, + ad groups that can show on the Microsoft Audience Network, and expired + ad groups. + + Args: + ad_account_id: Microsoft ad account id. Empty uses the config default. + campaign_id: Campaign id (from get_microsoft_campaigns); empty means + every campaign. + """ + from adloop.microsoft_ads.read import get_microsoft_ad_groups as _impl + + return _impl(current_config(), ad_account_id=ad_account_id, campaign_id=campaign_id) + + +@_tool(title="Microsoft Advertising keywords", annotations=_READONLY, tags={"microsoft_ads"}) +@_safe +def get_microsoft_keywords(ad_account_id: str = "", campaign_id: str = "", ad_group_id: str = "") -> dict: + """List Microsoft Advertising keywords with match type, bid, status and editorial review, plus the status of their ad group and campaign. + + Insights flag disapproved keywords and active broad-match keywords in + manual-bid campaigns. + + Args: + ad_account_id: Microsoft ad account id. Empty uses the config default. + campaign_id: Limit to one campaign; empty means every campaign. + ad_group_id: Limit to one ad group; empty means every ad group. + """ + from adloop.microsoft_ads.read import get_microsoft_keywords as _impl + + return _impl(current_config(), ad_account_id=ad_account_id, campaign_id=campaign_id, + ad_group_id=ad_group_id) + + +@_tool(title="Microsoft Advertising ads", annotations=_READONLY, tags={"microsoft_ads"}) +@_safe +def get_microsoft_ads(ad_account_id: str = "", campaign_id: str = "", ad_group_id: str = "") -> dict: + """List Microsoft Advertising ads with headlines, descriptions, paths, final URLs, status and editorial review. + + Insights flag disapproved ads and ad groups without an active ad. + + Args: + ad_account_id: Microsoft ad account id. Empty uses the config default. + campaign_id: Limit to one campaign; empty means every campaign. + ad_group_id: Limit to one ad group; empty means every ad group. + """ + from adloop.microsoft_ads.read import get_microsoft_ads as _impl + + return _impl(current_config(), ad_account_id=ad_account_id, campaign_id=campaign_id, + ad_group_id=ad_group_id) + + +@_tool(title="Microsoft Advertising performance", annotations=_READONLY, tags={"microsoft_ads"}) +@_safe +def get_microsoft_performance( + ad_account_id: str = "", + level: str = "campaign", + date_range_start: str = "", + date_range_end: str = "", + breakdown: str = "", + campaign_id: str = "", + compact: bool = False, +) -> dict: + """Microsoft Advertising performance: spend, impressions, clicks, CTR, CPC, conversions, CPA, revenue, impression share. + + Rows per entity for the chosen level with the status of each level, + totals and insights (zero-conversion spenders, converters losing + impressions to budget, spend under paused levels). Campaign and ad + group rows without a breakdown include impression share and the share + lost to budget and to rank. Built from a Microsoft report, which takes a + few seconds. + + Args: + ad_account_id: Microsoft ad account id. Empty uses the config default. + level: "account", "campaign" (default), "ad_group", "keyword" or "ad". + date_range_start: First day, YYYY-MM-DD, account time zone. Empty + means 29 days before date_range_end. + date_range_end: Last day (inclusive). Empty means yesterday. + breakdown: Optional "date" (daily rows) or "device". + campaign_id: Limit to one campaign; empty means the whole account. + compact: Totals, top 10 rows by spend and zero-conversion spenders + instead of every row. + """ + from adloop.microsoft_ads.read import get_microsoft_performance as _impl + + return _impl(current_config(), ad_account_id=ad_account_id, level=level, + date_range_start=date_range_start, date_range_end=date_range_end, + breakdown=breakdown, campaign_id=campaign_id, compact=compact) + + +@_tool(title="Microsoft Advertising search terms", annotations=_READONLY, tags={"microsoft_ads"}) +@_safe +def get_microsoft_search_terms( + ad_account_id: str = "", + date_range_start: str = "", + date_range_end: str = "", + campaign_id: str = "", + min_clicks: int = 2, + compact: bool = False, +) -> dict: + """Microsoft Advertising search terms: what people typed, the keyword and match type it matched, clicks, spend and conversions. + + Insights name terms with clicks and no conversion (negative keyword + candidates) and exact/phrase keywords matching broadly as close + variants. compact returns the top 25 terms by spend, the waste + candidates and the top converters. + + Args: + ad_account_id: Microsoft ad account id. Empty uses the config default. + date_range_start: First day, YYYY-MM-DD. Empty means 29 days before + date_range_end. + date_range_end: Last day (inclusive). Empty means yesterday. + campaign_id: Limit to one campaign; empty means the whole account. + min_clicks: Clicks from which a term without conversions counts as a + waste candidate (default 2). + compact: Summary instead of every term. + """ + from adloop.microsoft_ads.read import get_microsoft_search_terms as _impl + + return _impl(current_config(), ad_account_id=ad_account_id, date_range_start=date_range_start, + date_range_end=date_range_end, campaign_id=campaign_id, min_clicks=min_clicks, + compact=compact) + + +@_tool(title="Microsoft Advertising location report", annotations=_READONLY, tags={"microsoft_ads"}) +@_safe +def get_microsoft_location_performance( + ad_account_id: str = "", + date_range_start: str = "", + date_range_end: str = "", + campaign_id: str = "", + group_by: str = "city", +) -> dict: + """Where Microsoft Advertising clicks and spend came from, split into people physically there and people searching about the place. + + Rows per location with impressions, clicks, spend and conversions, and + the share of spend from 'location of interest' traffic (people elsewhere + searching about the area), which a local service business usually does + not want. + + Args: + ad_account_id: Microsoft ad account id. Empty uses the config default. + date_range_start: First day, YYYY-MM-DD. Empty means 29 days before + date_range_end. + date_range_end: Last day (inclusive). Empty means yesterday. + campaign_id: Limit to one campaign; empty means the whole account. + group_by: "city" (default), "metro", "state", "postal_code" or + "most_specific". + """ + from adloop.microsoft_ads.read import get_microsoft_location_performance as _impl + + return _impl(current_config(), ad_account_id=ad_account_id, date_range_start=date_range_start, + date_range_end=date_range_end, campaign_id=campaign_id, group_by=group_by) + + +@_tool(title="Microsoft Advertising conversion setup audit", annotations=_READONLY, tags={"microsoft_ads"}) +@_safe +def get_microsoft_conversion_setup( + ad_account_id: str = "", + date_range_start: str = "", + date_range_end: str = "", + min_clicks: int = 30, +) -> dict: + """Audit Microsoft Advertising conversion tracking: UET tags, conversion goals, campaign goals and conversions against clicks. + + Returns a verdict (ok, needs attention, broken) with checks[]: a UET tag + exists and is active; active goals exist, record conversions and count in + Conversions (not only All conversions); campaign-level goals; campaigns + with many clicks and no conversion. Also returns the tags, goals and + per-campaign clicks and conversions. + + Args: + ad_account_id: Microsoft ad account id. Empty uses the config default. + date_range_start: First day of the activity window, YYYY-MM-DD. + date_range_end: Last day (inclusive). Empty means yesterday. + min_clicks: Clicks from which a campaign without conversions is + flagged (default 30). + """ + from adloop.microsoft_ads.read import get_microsoft_conversion_setup as _impl + + return _impl(current_config(), ad_account_id=ad_account_id, date_range_start=date_range_start, + date_range_end=date_range_end, min_clicks=min_clicks) + + +@_tool(title="Draft a Microsoft Advertising campaign budget", annotations=_WRITE, tags={"microsoft_ads"}) +@_safe +def update_microsoft_campaign_budget(ad_account_id: str = "", campaign_id: str = "", daily_budget: float = 0.0) -> dict: + """Draft a new daily budget for a Microsoft Advertising campaign (preview only; nothing changes yet). + + Shows the current and new budget and the monthly maximum (30.4 × daily). + Refuses campaigns on a shared budget and amounts above the configured + safety cap (max_daily_budget). The returned plan_id is applied with + confirm_and_apply; a dry run re-reads the campaign and sends nothing, and + the apply refuses if the budget changed since the preview. + + Args: + ad_account_id: Microsoft ad account id. Empty uses the config default. + campaign_id: Campaign id (from get_microsoft_campaigns). + daily_budget: New daily budget in the account currency. + """ + from adloop.microsoft_ads.write import draft_microsoft_campaign_budget as _impl + + return _impl(current_config(), ad_account_id=ad_account_id, campaign_id=campaign_id, + daily_budget=daily_budget) + + +@_tool(title="Draft pausing a Microsoft Advertising entity", annotations=_WRITE, tags={"microsoft_ads"}) +@_safe +def pause_microsoft_entity(ad_account_id: str = "", entity_type: str = "", entity_id: str = "", parent_id: str = "") -> dict: + """Draft pausing a Microsoft Advertising campaign, ad group, keyword or ad (preview only). + + The preview names the entity, its campaign and ad group, and its current + status. The returned plan_id is applied with confirm_and_apply, which + refuses if the status changed since the preview. + + Args: + ad_account_id: Microsoft ad account id. Empty uses the config default. + entity_type: "campaign", "ad_group", "keyword" or "ad". + entity_id: The entity's id (from the read tools). + parent_id: Optional: the campaign id of an ad group, or the ad group + id of a keyword or ad, to find it faster. + """ + from adloop.microsoft_ads.write import draft_microsoft_status as _impl + + return _impl(current_config(), action="pause", ad_account_id=ad_account_id, + entity_type=entity_type, entity_id=entity_id, parent_id=parent_id) + + +@_tool(title="Draft enabling a Microsoft Advertising entity", annotations=_WRITE, tags={"microsoft_ads"}) +@_safe +def enable_microsoft_entity(ad_account_id: str = "", entity_type: str = "", entity_id: str = "", parent_id: str = "") -> dict: + """Draft enabling a paused Microsoft Advertising campaign, ad group, keyword or ad (preview only). + + Warnings name a paused parent or an editorial rejection that would still + keep it from serving. The returned plan_id is applied with + confirm_and_apply, which refuses if the status changed since the preview. + + Args: + ad_account_id: Microsoft ad account id. Empty uses the config default. + entity_type: "campaign", "ad_group", "keyword" or "ad". + entity_id: The entity's id (from the read tools). + parent_id: Optional: the campaign id of an ad group, or the ad group + id of a keyword or ad, to find it faster. + """ + from adloop.microsoft_ads.write import draft_microsoft_status as _impl + + return _impl(current_config(), action="enable", ad_account_id=ad_account_id, + entity_type=entity_type, entity_id=entity_id, parent_id=parent_id) + + +@_tool(title="Search Microsoft Advertising locations", annotations=_READONLY, tags={"microsoft_ads"}) +@_safe +def search_microsoft_locations(ad_account_id: str = "", query: str = "", location_type: str = "", limit: int = 20) -> dict: + """Find Microsoft Advertising location ids (countries, states, metros, cities, postal codes) by name. + + Reads Microsoft's geographic location file (cached until Microsoft + publishes a new version) and returns location_id, name, type and + status, the ids the targeting and new-campaign tools take. + + Args: + ad_account_id: Microsoft ad account id. Empty uses the config default. + query: Name or postal code, e.g. "Chicago" or "60601". + location_type: Optional filter such as "City", "Metro", "State" or "PostalCode". + limit: Most results (1–100). + """ + from adloop.microsoft_ads.read import search_microsoft_locations as _impl + + return _impl(current_config(), ad_account_id=ad_account_id, query=query, location_type=location_type, limit=limit) + + +@_tool(title="Microsoft Advertising negative keywords", annotations=_READONLY, tags={"microsoft_ads"}) +@_safe +def get_microsoft_negative_keywords(ad_account_id: str = "", campaign_id: str = "") -> dict: + """List Microsoft Advertising negative keywords: those directly on campaigns and the shared negative keyword lists. + + Each list shows its keywords, the campaigns it is attached to and a + remove_id per keyword; direct negatives also carry a remove_id. + Insights flag direct negatives and lists attached to nothing. + + Args: + ad_account_id: Microsoft ad account id. Empty uses the config default. + campaign_id: Limit to one campaign and the lists attached to it. + """ + from adloop.microsoft_ads.manage import get_microsoft_negative_keywords as _impl + + return _impl(current_config(), ad_account_id=ad_account_id, campaign_id=campaign_id) + + +@_tool(title="Microsoft Advertising ad extensions", annotations=_READONLY, tags={"microsoft_ads"}) +@_safe +def get_microsoft_ad_extensions(ad_account_id: str = "", campaign_id: str = "") -> dict: + """List sitelinks, callouts, structured snippets, call and image extensions on Microsoft Advertising ad groups, campaigns and the account. + + Each row has the level (account, campaign or ad_group), type, content, + final URLs, editorial status and the remove_id that unlinks it. Image + rows add alt_text, display_text, layouts, media_ids and images: each + image's media type, size and a url that opens the picture, so a photo + can be checked before its link is removed. Insights flag campaigns + without sitelinks, disapproved extensions and accounts without image + extensions. + + Args: + ad_account_id: Microsoft ad account id. Empty uses the config default. + campaign_id: Limit to one campaign. + """ + from adloop.microsoft_ads.manage import get_microsoft_ad_extensions as _impl + + return _impl(current_config(), ad_account_id=ad_account_id, campaign_id=campaign_id) + + +@_tool(title="Draft Microsoft Advertising campaign settings", annotations=_WRITE, tags={"microsoft_ads"}) +@_safe +def update_microsoft_campaign( + ad_account_id: str = "", + campaign_id: str = "", + name: str = "", + bidding_strategy: str = "", + target_cpa: float | None = None, + max_cpc: float | None = None, + tracking_url_template: str | None = None, + final_url_suffix: str | None = None, +) -> dict: + """Draft Microsoft Advertising campaign setting changes: name, bid strategy and targets, tracking template, final URL suffix. + + Bid strategies: ManualCpc, EnhancedCpc, MaxClicks, MaxConversions (with + an optional target_cpa; TargetCpa is accepted and becomes MaxConversions, + as Microsoft now does). Moving to manual bidding is refused while the + campaign has active broad-match keywords. The daily budget has its own + tool, update_microsoft_campaign_budget. The returned plan_id is applied + with confirm_and_apply, which refuses if a changed setting was edited + after the preview. + + Args: + ad_account_id: Microsoft ad account id. Empty uses the config default. + campaign_id: Campaign id. + name: New name (at most 128 characters, unique in the account). + bidding_strategy: ManualCpc, EnhancedCpc, MaxClicks or MaxConversions. + target_cpa: Target cost per conversion for MaxConversions. + max_cpc: Maximum CPC for MaxClicks / MaxConversions (only changes an existing cap). + tracking_url_template: New template ({lpurl}...); "" removes it. + final_url_suffix: New suffix (e.g. utm parameters); "" removes it. + """ + from adloop.microsoft_ads.manage import update_microsoft_campaign as _impl + + return _impl(current_config(), ad_account_id=ad_account_id, campaign_id=campaign_id, name=name, + bidding_strategy=bidding_strategy, target_cpa=target_cpa, max_cpc=max_cpc, + tracking_url_template=tracking_url_template, final_url_suffix=final_url_suffix) + + +@_tool(title="Draft Microsoft Advertising targeting changes", annotations=_WRITE, tags={"microsoft_ads"}) +@_safe +def update_microsoft_campaign_targeting( + ad_account_id: str = "", + campaign_id: str = "", + location_ids: _StrListOpt = None, + excluded_location_ids: _StrListOpt = None, + location_intent: str = "", + ad_schedule: _DictListOpt = None, +) -> dict: + """Draft Microsoft Advertising campaign targeting: included and excluded locations, location intent, ad schedule. + + Location lists are the full new sets; the preview shows what is added + and removed. location_intent PeopleIn keeps ads to people in the + locations. ad_schedule replaces every window ([] serves at all hours); + the hours follow the account time zone, or each searcher's own when the + campaign uses AdScheduleUseSearcherTimeZone (the preview says which), and + a campaign's first schedule needs a double confirmation because it + switches all other hours off. + The returned plan_id is applied with confirm_and_apply, which refuses if + the targeting changed after the preview. + + Args: + ad_account_id: Microsoft ad account id. Empty uses the config default. + campaign_id: Campaign id. + location_ids: Full new list of included location ids (search_microsoft_locations); cannot be empty. + excluded_location_ids: Full new list of excluded location ids. + location_intent: PeopleIn or PeopleInOrSearchingForOrViewingPages. + ad_schedule: Windows like {"day_of_week": "Monday", "start_hour": 8, "end_hour": 17, + "start_minute": 0, "end_minute": 0} (minutes 0/15/30/45). + """ + from adloop.microsoft_ads.manage import update_microsoft_campaign_targeting as _impl + + return _impl(current_config(), ad_account_id=ad_account_id, campaign_id=campaign_id, location_ids=location_ids, + excluded_location_ids=excluded_location_ids, location_intent=location_intent, ad_schedule=ad_schedule) + + +@_tool(title="Draft a Microsoft Advertising campaign", annotations=_WRITE, tags={"microsoft_ads"}) +@_safe +def draft_microsoft_campaign( + ad_account_id: str = "", + name: str = "", + daily_budget: float = 0.0, + bidding_strategy: str = "MaxConversions", + target_cpa: float | None = None, + languages: _StrListOpt = None, + location_ids: _StrListOpt = None, + excluded_location_ids: _StrListOpt = None, + location_intent: str = "PeopleIn", + tracking_url_template: str = "", + final_url_suffix: str = "", +) -> dict: + """Draft a new Microsoft Advertising Search campaign, created PAUSED with its locations (preview only). + + Requires a daily budget (capped by max_daily_budget), languages and + included locations. Defaults to MaxConversions and PeopleIn; warns when + no conversion goal counts toward Conversions. The apply creates the + campaign, then its location criteria, and names what was created if the + second step fails. The returned plan_id is applied with confirm_and_apply. + + Args: + ad_account_id: Microsoft ad account id. Empty uses the config default. + name: Campaign name (unique, at most 128 characters). + daily_budget: Daily budget in the account currency. + bidding_strategy: MaxConversions (default), MaxClicks, EnhancedCpc or ManualCpc. + target_cpa: Optional target cost per conversion. + languages: Ad languages, e.g. ["English"]. + location_ids: Included location ids (search_microsoft_locations). + excluded_location_ids: Excluded location ids. + location_intent: PeopleIn (default) or PeopleInOrSearchingForOrViewingPages. + tracking_url_template: Optional tracking template. + final_url_suffix: Optional final URL suffix (e.g. utm parameters). + """ + from adloop.microsoft_ads.manage import draft_microsoft_campaign as _impl + + return _impl(current_config(), ad_account_id=ad_account_id, name=name, daily_budget=daily_budget, + bidding_strategy=bidding_strategy, target_cpa=target_cpa, languages=languages, + location_ids=location_ids, excluded_location_ids=excluded_location_ids, + location_intent=location_intent, tracking_url_template=tracking_url_template, + final_url_suffix=final_url_suffix) + + +@_tool(title="Draft a Microsoft Advertising ad group", annotations=_WRITE, tags={"microsoft_ads"}) +@_safe +def draft_microsoft_ad_group( + ad_account_id: str = "", + campaign_id: str = "", + name: str = "", + cpc_bid: float | None = None, + network: str = "OwnedAndOperatedOnly", + keywords: _StrOrDictListOpt = None, +) -> dict: + """Draft a new Microsoft Advertising ad group, optionally with keywords (preview only). + + The ad group is created active but serves only once one of its ads (new + ads are paused) is enabled. Manual-bid campaigns need cpc_bid; broad + match is refused unless the campaign uses automated bidding. network + OwnedAndOperatedOnly (default) keeps ads off syndicated partner sites. + The returned plan_id is applied with confirm_and_apply. + + Args: + ad_account_id: Microsoft ad account id. Empty uses the config default. + campaign_id: Parent campaign id. + name: Ad group name (unique in the campaign). + cpc_bid: Default max CPC in the account currency. + network: OwnedAndOperatedOnly or OwnedAndOperatedAndSyndicatedSearch. + keywords: Keywords as text or {"text", "match_type": Exact|Phrase|Broad, "bid"}; text defaults to Phrase. + """ + from adloop.microsoft_ads.manage import draft_microsoft_ad_group as _impl + + return _impl(current_config(), ad_account_id=ad_account_id, campaign_id=campaign_id, name=name, + cpc_bid=cpc_bid, network=network, keywords=keywords) + + +@_tool(title="Draft Microsoft Advertising ad group changes", annotations=_WRITE, tags={"microsoft_ads"}) +@_safe +def update_microsoft_ad_group( + ad_account_id: str = "", + ad_group_id: str = "", + name: str = "", + cpc_bid: float | None = None, + network: str = "", + audience_ads_bid_adjustment: int | None = None, +) -> dict: + """Draft Microsoft Advertising ad group changes: name, default bid, search network, Audience Network adjustment. + + A bid raise is capped by max_bid_increase_pct. audience_ads_bid_adjustment + -100 keeps the ad group off the Microsoft Audience Network. The returned + plan_id is applied with confirm_and_apply, which refuses if a changed + setting was edited after the preview. + + Args: + ad_account_id: Microsoft ad account id. Empty uses the config default. + ad_group_id: Ad group id. + name: New name. + cpc_bid: New default max CPC. + network: OwnedAndOperatedOnly or OwnedAndOperatedAndSyndicatedSearch. + audience_ads_bid_adjustment: -100 (off) to 900 percent. + """ + from adloop.microsoft_ads.manage import update_microsoft_ad_group as _impl + + return _impl(current_config(), ad_account_id=ad_account_id, ad_group_id=ad_group_id, name=name, + cpc_bid=cpc_bid, network=network, audience_ads_bid_adjustment=audience_ads_bid_adjustment) + + +@_tool(title="Draft Microsoft Advertising keywords", annotations=_WRITE, tags={"microsoft_ads"}) +@_safe +def draft_microsoft_keywords(ad_account_id: str = "", ad_group_id: str = "", keywords: _StrOrDictListOpt = None) -> dict: + """Draft adding keywords to a Microsoft Advertising ad group (preview only). + + Keywords already in the ad group are skipped; broad match is refused + unless the campaign uses automated bidding. The returned plan_id is + applied with confirm_and_apply. + + Args: + ad_account_id: Microsoft ad account id. Empty uses the config default. + ad_group_id: Ad group id. + keywords: Text or {"text", "match_type": Exact|Phrase|Broad, "bid"}; text defaults to Phrase. + """ + from adloop.microsoft_ads.manage import draft_microsoft_keywords as _impl + + return _impl(current_config(), ad_account_id=ad_account_id, ad_group_id=ad_group_id, keywords=keywords) + + +@_tool(title="Draft Microsoft Advertising keyword bids", annotations=_WRITE, tags={"microsoft_ads"}) +@_safe +def update_microsoft_keyword_bids(ad_account_id: str = "", ad_group_id: str = "", bids: _DictListOpt = None) -> dict: + """Draft keyword bid changes in one Microsoft Advertising ad group (preview only). + + Each raise is capped by max_bid_increase_pct against the keyword's + current bid (or the ad group default). A null bid removes the keyword's + own bid so the ad group default applies. The returned plan_id is applied + with confirm_and_apply, which refuses if a bid changed after the preview. + + Args: + ad_account_id: Microsoft ad account id. Empty uses the config default. + ad_group_id: Ad group id. + bids: [{"keyword_id", "bid"}]. + """ + from adloop.microsoft_ads.manage import update_microsoft_keyword_bids as _impl + + return _impl(current_config(), ad_account_id=ad_account_id, ad_group_id=ad_group_id, bids=bids) + + +@_tool(title="Draft Microsoft Advertising negative keywords", annotations=_WRITE, tags={"microsoft_ads"}) +@_safe +def add_microsoft_negative_keywords( + ad_account_id: str = "", + campaign_id: str = "", + ad_group_id: str = "", + keywords: _StrListOpt = None, + match_type: str = "Phrase", +) -> dict: + """Draft negative keywords directly on one Microsoft Advertising campaign or ad group (preview only). + + Negatives already there are skipped, and the preview names active + keywords they would block. A shared list (propose_microsoft_negative_keyword_list) + is the reusable alternative. The returned plan_id is applied with + confirm_and_apply. + + Args: + ad_account_id: Microsoft ad account id. Empty uses the config default. + campaign_id: Campaign id (or ad_group_id, not both). + ad_group_id: Ad group id. + keywords: Negative keyword texts. + match_type: Phrase (default) or Exact. + """ + from adloop.microsoft_ads.manage import add_microsoft_negative_keywords as _impl + + return _impl(current_config(), ad_account_id=ad_account_id, campaign_id=campaign_id, ad_group_id=ad_group_id, + keywords=keywords, match_type=match_type) + + +@_tool(title="Draft a Microsoft Advertising negative keyword list", annotations=_WRITE, tags={"microsoft_ads"}) +@_safe +def propose_microsoft_negative_keyword_list( + ad_account_id: str = "", + list_name: str = "", + keywords: _StrListOpt = None, + match_type: str = "Phrase", + campaign_ids: _StrListOpt = None, +) -> dict: + """Draft a new shared Microsoft Advertising negative keyword list and attach it to campaigns (preview only). + + Refuses a name that already exists (add_to_microsoft_negative_keyword_list + appends to it) and campaigns already at Microsoft's 20-list limit; the + preview names active keywords the negatives would block. The returned + plan_id is applied with confirm_and_apply. + + Args: + ad_account_id: Microsoft ad account id. Empty uses the config default. + list_name: List name. + keywords: Negative keyword texts (up to 5,000). + match_type: Phrase (default) or Exact. + campaign_ids: Campaigns to attach the list to. + """ + from adloop.microsoft_ads.manage import propose_microsoft_negative_keyword_list as _impl + + return _impl(current_config(), ad_account_id=ad_account_id, list_name=list_name, keywords=keywords, + match_type=match_type, campaign_ids=campaign_ids) + + +@_tool(title="Draft adding to a Microsoft Advertising negative list", annotations=_WRITE, tags={"microsoft_ads"}) +@_safe +def add_to_microsoft_negative_keyword_list( + ad_account_id: str = "", list_id: str = "", keywords: _StrListOpt = None, match_type: str = "Phrase", +) -> dict: + """Draft appending negatives to an existing Microsoft Advertising negative keyword list (preview only). + + Items already in the list are skipped; the preview names active + keywords in attached campaigns that the new negatives would block. The + returned plan_id is applied with confirm_and_apply. + + Args: + ad_account_id: Microsoft ad account id. Empty uses the config default. + list_id: Shared list id (get_microsoft_negative_keywords). + keywords: Negative keyword texts. + match_type: Phrase (default) or Exact. + """ + from adloop.microsoft_ads.manage import add_to_microsoft_negative_keyword_list as _impl + + return _impl(current_config(), ad_account_id=ad_account_id, list_id=list_id, keywords=keywords, match_type=match_type) + + +@_tool(title="Draft attaching a Microsoft Advertising negative list", annotations=_WRITE, tags={"microsoft_ads"}) +@_safe +def attach_microsoft_negative_keyword_list(ad_account_id: str = "", list_id: str = "", campaign_ids: _StrListOpt = None) -> dict: + """Draft attaching a shared Microsoft Advertising negative keyword list to campaigns (preview only). + + Campaigns already attached are skipped. The returned plan_id is applied + with confirm_and_apply. + + Args: + ad_account_id: Microsoft ad account id. Empty uses the config default. + list_id: Shared list id. + campaign_ids: Campaign ids. + """ + from adloop.microsoft_ads.manage import attach_microsoft_negative_keyword_list as _impl + + return _impl(current_config(), ad_account_id=ad_account_id, list_id=list_id, campaign_ids=campaign_ids) + + +@_tool(title="Draft detaching a Microsoft Advertising negative list", annotations=_WRITE, tags={"microsoft_ads"}) +@_safe +def detach_microsoft_negative_keyword_list(ad_account_id: str = "", list_id: str = "", campaign_ids: _StrListOpt = None) -> dict: + """Draft detaching a shared Microsoft Advertising negative keyword list from campaigns; the list stays (preview only). + + The returned plan_id is applied with confirm_and_apply. + + Args: + ad_account_id: Microsoft ad account id. Empty uses the config default. + list_id: Shared list id. + campaign_ids: Campaign ids. + """ + from adloop.microsoft_ads.manage import detach_microsoft_negative_keyword_list as _impl + + return _impl(current_config(), ad_account_id=ad_account_id, list_id=list_id, campaign_ids=campaign_ids) + + +@_tool(title="Draft a Microsoft Advertising responsive search ad", annotations=_WRITE, tags={"microsoft_ads"}) +@_safe +def draft_microsoft_responsive_search_ad( + ad_account_id: str = "", + ad_group_id: str = "", + headlines: _StrOrDictListOpt = None, + descriptions: _StrOrDictListOpt = None, + final_url: str = "", + path1: str = "", + path2: str = "", +) -> dict: + """Draft a Microsoft Advertising responsive search ad, created PAUSED (preview only). + + Checks 3–15 headlines of at most 30 characters, 2–4 descriptions of at + most 90, display paths of at most 15, pin slots that stay fillable and a + reachable landing page. The returned plan_id is applied with + confirm_and_apply; the dry run refuses an identical ad already in the + ad group. + + Args: + ad_account_id: Microsoft ad account id. Empty uses the config default. + ad_group_id: Ad group id. + headlines: Text or {"text", "pinned_field": HEADLINE_1|HEADLINE_2|HEADLINE_3}. + descriptions: Text or {"text", "pinned_field": DESCRIPTION_1|DESCRIPTION_2}. + final_url: Landing page. + path1: First display path. + path2: Second display path (needs path1). + """ + from adloop.microsoft_ads.manage import draft_microsoft_responsive_search_ad as _impl + + return _impl(current_config(), ad_account_id=ad_account_id, ad_group_id=ad_group_id, headlines=headlines, + descriptions=descriptions, final_url=final_url, path1=path1, path2=path2) + + +@_tool(title="Draft Microsoft Advertising responsive search ad changes", annotations=_WRITE, tags={"microsoft_ads"}) +@_safe +def update_microsoft_responsive_search_ad( + ad_account_id: str = "", + ad_id: str = "", + headlines: _StrOrDictListOpt = None, + descriptions: _StrOrDictListOpt = None, + final_url: str = "", + path1: str | None = None, + path2: str | None = None, +) -> dict: + """Draft changes to a Microsoft Advertising responsive search ad (preview only). + + headlines or descriptions replace that whole list; paths "" remove + them. Edited ads go back to editorial review. The returned plan_id is + applied with confirm_and_apply, which refuses if the ad changed after + the preview. + + Args: + ad_account_id: Microsoft ad account id. Empty uses the config default. + ad_id: Ad id. + headlines: Full new list (text or {"text", "pinned_field"}). + descriptions: Full new list. + final_url: New landing page. + path1: New first display path; "" removes it. + path2: New second display path; "" removes it. + """ + from adloop.microsoft_ads.manage import update_microsoft_responsive_search_ad as _impl + + return _impl(current_config(), ad_account_id=ad_account_id, ad_id=ad_id, headlines=headlines, + descriptions=descriptions, final_url=final_url, path1=path1, path2=path2) + + +@_tool(title="Draft Microsoft Advertising sitelinks", annotations=_WRITE, tags={"microsoft_ads"}) +@_safe +def draft_microsoft_sitelinks(ad_account_id: str = "", campaign_id: str = "", scope: str = "", sitelinks: _DictListOpt = None) -> dict: + """Draft sitelinks for a Microsoft Advertising campaign or the account (preview only). + + Link text is at most 25 characters with descriptions (35 without); + descriptions come in pairs of at most 35; every URL is checked. + Sitelinks already linked are skipped. The returned plan_id is applied + with confirm_and_apply. + + Args: + ad_account_id: Microsoft ad account id. Empty uses the config default. + campaign_id: Campaign id (or scope="account"). + scope: "account" links them to every campaign without its own. + sitelinks: [{"link_text", "final_url", "description1", "description2"}]. + """ + from adloop.microsoft_ads.manage import draft_microsoft_sitelinks as _impl + + return _impl(current_config(), ad_account_id=ad_account_id, campaign_id=campaign_id, scope=scope, sitelinks=sitelinks) + + +@_tool(title="Draft Microsoft Advertising callouts", annotations=_WRITE, tags={"microsoft_ads"}) +@_safe +def draft_microsoft_callouts(ad_account_id: str = "", campaign_id: str = "", scope: str = "", callouts: _StrListOpt = None) -> dict: + """Draft callouts (at most 25 characters each) for a Microsoft Advertising campaign or the account (preview only). + + Callouts already linked are skipped. The returned plan_id is applied + with confirm_and_apply. + + Args: + ad_account_id: Microsoft ad account id. Empty uses the config default. + campaign_id: Campaign id (or scope="account"). + scope: "account" links them account-wide. + callouts: Callout texts. + """ + from adloop.microsoft_ads.manage import draft_microsoft_callouts as _impl + + return _impl(current_config(), ad_account_id=ad_account_id, campaign_id=campaign_id, scope=scope, callouts=callouts) + + +@_tool(title="Draft a Microsoft Advertising structured snippet", annotations=_WRITE, tags={"microsoft_ads"}) +@_safe +def draft_microsoft_structured_snippet( + ad_account_id: str = "", campaign_id: str = "", scope: str = "", header: str = "", values: _StrListOpt = None, +) -> dict: + """Draft a structured snippet (a header and 3–10 values) for a Microsoft Advertising campaign or the account (preview only). + + The returned plan_id is applied with confirm_and_apply. + + Args: + ad_account_id: Microsoft ad account id. Empty uses the config default. + campaign_id: Campaign id (or scope="account"). + scope: "account" links it account-wide. + header: Microsoft header such as Services, Brands, Types. + values: 3–10 values of at most 25 characters. + """ + from adloop.microsoft_ads.manage import draft_microsoft_structured_snippet as _impl + + return _impl(current_config(), ad_account_id=ad_account_id, campaign_id=campaign_id, scope=scope, header=header, values=values) + + +@_tool(title="Draft a Microsoft Advertising call extension", annotations=_WRITE, tags={"microsoft_ads"}) +@_safe +def draft_microsoft_call_extension(ad_account_id: str = "", campaign_id: str = "", phone_number: str = "", country_code: str = "") -> dict: + """Draft a call extension (phone number shown with the ads) for one Microsoft Advertising campaign (preview only). + + Microsoft allows one per campaign; a campaign that already has one is + refused. The returned plan_id is applied with confirm_and_apply. + + Args: + ad_account_id: Microsoft ad account id. Empty uses the config default. + campaign_id: Campaign id. + phone_number: The number to show (usually a call-tracking number). + country_code: Two-letter country of the number, e.g. US. + """ + from adloop.microsoft_ads.manage import draft_microsoft_call_extension as _impl + + return _impl(current_config(), ad_account_id=ad_account_id, campaign_id=campaign_id, phone_number=phone_number, + country_code=country_code) + + +@_tool(title="Draft Microsoft Advertising image extensions", annotations=_WRITE, tags={"microsoft_ads"}) +@_safe +def draft_microsoft_image_extension( + ad_account_id: str = "", + campaign_id: str = "", + ad_group_id: str = "", + scope: str = "", + image_paths: _StrList = [], # noqa: B006 + image_urls: _StrList = [], # noqa: B006 + upload_ids: _StrList = [], # noqa: B006 + alt_text: str = "", + display_text: str = "", + final_url: str = "", +) -> dict: + """Draft image extensions (photos shown with Microsoft search ads) for a campaign, an ad group or the account (preview only). + + One image extension per image, up to 10 images. Each image is checked + now against Microsoft's requirements: JPEG, PNG or non-animated GIF, at + most 5 MB, a 1.91:1 aspect ratio (e.g. 1200x628), at least 703x368 and + at most 2592 wide and 2048 high; a bad image is refused with the reason. + Applying uploads the images to the account's media library, creates the + extensions and links them; the dry run reads every image again and + refuses one that changed. Image extensions can also take the ads into + native placements on the Microsoft Audience Network. The returned + plan_id is applied with confirm_and_apply. + + Args: + ad_account_id: Microsoft ad account id. Empty uses the config default. + campaign_id: Campaign id (or ad_group_id, or scope="account"). + ad_group_id: Ad group id (from get_microsoft_ad_groups). + scope: "account" links them to the whole account. + image_paths: Local image files on the machine running AdLoop (not on + a hosted server). + image_urls: Public http(s) image URLs; private or internal addresses + are refused. + upload_ids: Ids of uploaded images (up_..., from upload_images or + list_uploads), for images without a public URL. + alt_text: Required, at most 35 characters: describes the image for + screen readers and shows on hover. Used for every image. + display_text: Optional caption (at most 35 characters) shown under each + image in the multi-image layout; passing it makes the extensions + eligible for that layout too. + final_url: Optional landing page for clicks on the image (checked); + empty uses the ad's own final URL. + """ + from adloop.microsoft_ads.manage import draft_microsoft_image_extension as _impl + + return _impl(current_config(), ad_account_id=ad_account_id, campaign_id=campaign_id, ad_group_id=ad_group_id, + scope=scope, image_paths=image_paths, image_urls=image_urls, upload_ids=upload_ids, + alt_text=alt_text, display_text=display_text, final_url=final_url) + + +@_tool(title="Draft removing a Microsoft Advertising entity", annotations=_DESTRUCTIVE, tags={"microsoft_ads"}) +@_safe +def remove_microsoft_entity(ad_account_id: str = "", entity_type: str = "", entity_id: str = "") -> dict: + """Draft deleting a Microsoft Advertising entity: irreversible, double confirmation (preview only). + + Removes a campaign, ad group, ad or keyword by id, or (by the remove_id + the read tools return) a direct negative keyword, a negative list item, + a location or schedule criterion, or an extension link (account, + campaign or ad group, image extensions included). Pausing keeps + history and can be undone. The returned plan_id is applied with + confirm_and_apply. + + Args: + ad_account_id: Microsoft ad account id. Empty uses the config default. + entity_type: campaign, ad_group, ad, keyword, negative_keyword, + negative_list_item, campaign_criterion or extension_association. + entity_id: The id, or the remove_id for the composite types. + """ + from adloop.microsoft_ads.manage import remove_microsoft_entity as _impl + + return _impl(current_config(), ad_account_id=ad_account_id, entity_type=entity_type, entity_id=entity_id) + + # --------------------------------------------------------------------------- # Tracking Tools # --------------------------------------------------------------------------- diff --git a/src/adloop/uploads.py b/src/adloop/uploads.py index ad3a94f4..74e07ee3 100644 --- a/src/adloop/uploads.py +++ b/src/adloop/uploads.py @@ -5,7 +5,8 @@ ``store_image_upload`` tool with the file, or, on a hosted server, the user opens a one-time upload link. Either way the image lands in an :class:`UploadStore` under an ``up_...`` id, and the tools take that id: -``draft_image_assets(upload_ids=[...])`` for Google Ads, ``upload:`` in +``draft_image_assets(upload_ids=[...])`` for Google Ads, +``draft_microsoft_image_extension(upload_ids=[...])`` for Microsoft, ``upload:`` in the media fields of ``draft_reddit_ad``. Conversion CSVs take the same path (``upload_conversion_csv``) and go into diff --git a/tests/test_health_check.py b/tests/test_health_check.py index f69ee8ee..e4b53bff 100644 --- a/tests/test_health_check.py +++ b/tests/test_health_check.py @@ -127,3 +127,32 @@ async def test_server_announces_its_icons_and_website(): "https://getadloop.com/icon-512.png", "https://getadloop.com/favicon.svg", ] + + +def test_hosted_provider_without_an_integration_reports_not_configured(monkeypatch, stub_other_services): + """Hosted, a provider that does not support an ad platform means the + platform is not offered, even when shared config names its app.""" + import adloop.ga4.reports as reports + from adloop import auth + from adloop.config import MicrosoftAdsConfig + + class OlderProvider: + pass + + def no_local_files(*_a, **_k): + raise AssertionError("hosted mode must not read local credential files") + + monkeypatch.setattr("adloop.runtime.deployment_mode", lambda: "server") + monkeypatch.setattr("adloop.microsoft_ads.auth.local_credentials", no_local_files) + monkeypatch.setattr(reports, "get_account_summaries", lambda _c: _summaries()) + monkeypatch.setattr(reports, "probe_data_api", lambda _c, _p: None) + previous = auth.get_credentials_provider() + auth.set_credentials_provider(OlderProvider()) + runtime.set_default_config(AdLoopConfig( + microsoft_ads=MicrosoftAdsConfig(developer_token="dev-token", client_id="app-id"), + )) + try: + status = server.health_check() + finally: + auth.set_credentials_provider(previous) + assert status["microsoft_ads"] == "not_configured" diff --git a/tests/test_microsoft_ads.py b/tests/test_microsoft_ads.py new file mode 100644 index 00000000..75ce6bd4 --- /dev/null +++ b/tests/test_microsoft_ads.py @@ -0,0 +1,1205 @@ +"""Microsoft Advertising: config, OAuth, REST client, reports, reads, writes and the apply gate.""" + +from __future__ import annotations + +import io +import json +import os +import stat +import zipfile +from datetime import date, timedelta +from unittest.mock import patch + +import pytest + +from adloop.config import AdLoopConfig, MicrosoftAdsConfig, SafetyConfig, load_config +from adloop.microsoft_ads import auth, client, read, write +from adloop.microsoft_ads.auth import MicrosoftAdsApiError, MicrosoftAdsAuthError, MicrosoftCredentials +from adloop.safety import preview as preview_store +from adloop.safety.preview import InMemoryPlanStore + +ACCOUNT = "100200300" +CUSTOMER = "900800700" +_LOG_FILE = "" + + +@pytest.fixture(autouse=True) +def _fresh_state(tmp_path): + global _LOG_FILE + _LOG_FILE = str(tmp_path / "audit.log") + preview_store.set_plan_store(InMemoryPlanStore()) + read.reset_account_cache() + auth.reset_credentials_cache() + yield + preview_store.set_plan_store(InMemoryPlanStore()) + + +def _config(**safety) -> AdLoopConfig: + kwargs = dict(max_daily_budget=50.0, require_dry_run=False, log_file=_LOG_FILE) + kwargs.update(safety) + return AdLoopConfig( + microsoft_ads=MicrosoftAdsConfig( + developer_token="dev-token", client_id="app-id", customer_id=CUSTOMER, ad_account_id=ACCOUNT, + ), + safety=SafetyConfig(**kwargs), + ) + + +class _Creds(MicrosoftCredentials): + def __init__(self): + super().__init__(client_id="app-id", refresh_token="rt", access_token="at-1", expires_at=10**12) + self.refreshes = 0 + + def _refresh_locked(self): + self.refreshes += 1 + self.access_token = f"at-{self.refreshes + 1}" + self.expires_at = 10**12 + + +@pytest.fixture +def creds(): + c = _Creds() + with patch("adloop.microsoft_ads.client._credentials", return_value=c): + yield c + + +# --------------------------------------------------------------------------- +# Fake API +# --------------------------------------------------------------------------- + +_ACCOUNT = {"Account": {"Id": ACCOUNT, "Name": "Acme Plumbing", "Number": "X0000AAA", "CurrencyCode": "USD", + "TimeZone": "PacificTimeUSCanadaTijuana", "AccountLifeCycleStatus": "Active", + "ParentCustomerId": CUSTOMER}} +_CAMPAIGNS = {"Campaigns": [ + {"Id": "500100200", "Name": "Acme Plumbing - Search", "Status": "Active", "CampaignType": "Search", + "DailyBudget": 35.0, "BudgetType": "DailyBudgetStandard", "BudgetId": None, + "BiddingScheme": {"Type": "MaxClicksBiddingScheme", "MaxCpc": {"Amount": 9.0}}, + "Languages": ["English"], "GoalIds": None}, + {"Id": "600", "Name": "Shared", "Status": "Paused", "CampaignType": "Search", "DailyBudget": 50.0, + "BudgetId": "777", "BiddingScheme": {"Type": "ManualCpcBiddingScheme"}}, +]} +_CRITERIONS = { + ("500100200", "Location"): [ + {"Type": "BiddableCampaignCriterion", "Criterion": {"Type": "LocationCriterion", "DisplayName": "62704", + "LocationId": "1", "LocationType": "PostalCode"}}, + {"Type": "NegativeCampaignCriterion", "Criterion": {"Type": "LocationCriterion", "DisplayName": "Chatham", + "LocationId": "2", "LocationType": "City"}}, + ], + ("500100200", "LocationIntent"): [ + {"Type": "BiddableCampaignCriterion", + "Criterion": {"Type": "LocationIntentCriterion", "IntentOption": "PeopleInOrSearchingForOrViewingPages"}}, + ], +} +_AD_GROUPS = { + "500100200": [ + {"Id": "11", "Name": "Drains", "Status": "Active", "CpcBid": {"Amount": 4.5}, + "Network": "OwnedAndOperatedAndSyndicatedSearch", "Language": "English", "AudienceAdsBidAdjustment": 0}, + {"Id": "12", "Name": "Water heaters", "Status": "Paused", "CpcBid": {"Amount": 5.0}, + "Network": "OwnedAndOperatedOnly", "AudienceAdsBidAdjustment": -100}, + ], + "600": [], +} +_KEYWORDS = { + "11": [{"Id": "101", "Text": "drain cleaning", "MatchType": "Phrase", "Bid": {"Amount": None}, + "Status": "Active", "EditorialStatus": "Active"}, + {"Id": "102", "Text": "plumber", "MatchType": "Broad", "Status": "Active", "EditorialStatus": "Disapproved"}], + "12": [{"Id": "103", "Text": "water heater", "MatchType": "Exact", "Status": "Active"}], +} +_ADS = { + "11": [{"Id": "201", "Type": "ResponsiveSearch", "Status": "Active", "EditorialStatus": "Active", + "Headlines": [{"Asset": {"Text": "Drain Cleaning $69", "Type": "TextAsset"}, "PinnedField": "Headline1"}, + {"Asset": {"Text": "Springfield Plumber"}}], + "Descriptions": [{"Asset": {"Text": "Licensed local plumbers."}}], + "FinalUrls": ["https://example.com/drain"], "Path1": "drain"}], + "12": [{"Id": "202", "Type": "ResponsiveSearch", "Status": "Paused", "EditorialStatus": "Active", + "Headlines": [], "Descriptions": [], "FinalUrls": []}], +} +_TAGS = {"UetTags": [{"Id": "400500600", "Name": "Main site", "TrackingStatus": "Unverified"}]} +_GOALS = {"ConversionGoals": [ + {"Id": "9", "Name": "Web Form Lead", "Type": "Event", "Status": "Active", "TrackingStatus": "NoRecentConversions", + "ExcludeFromBidding": False, "ConversionWindowInMinutes": 43200, "TagId": "400500600", "Scope": "Account"}, + {"Id": "10", "Name": "Thank you page", "Type": "Url", "Status": "Active", "TrackingStatus": "TagUnverified", + "ExcludeFromBidding": True}, +]} + + +def _csv(rows: list[dict], zipped: bool = True) -> bytes: + if not rows: + text = "" + else: + buf = io.StringIO() + import csv as _csvmod + + writer = _csvmod.DictWriter(buf, fieldnames=list(rows[0])) + writer.writeheader() + writer.writerows(rows) + text = "" + buf.getvalue() + data = text.encode("utf-8") + if not zipped: + return data + out = io.BytesIO() + with zipfile.ZipFile(out, "w") as archive: + archive.writestr("report.csv", data) + return out.getvalue() + + +_REPORTS = { + "CampaignPerformanceReportRequest": [ + {"CampaignId": "500100200", "CampaignName": "Acme Plumbing - Search", "CampaignStatus": "Active", + "CampaignType": "Search", "Impressions": "1,200", "Clicks": "45", "Spend": "382.10", "Ctr": "3.75%", + "AverageCpc": "8.49", "ConversionsQualified": "0", + "Revenue": "0.00", "ImpressionSharePercent": "12.5", "ImpressionLostToBudgetPercent": "41.2", + "ImpressionLostToRankAggPercent": "46.3", "AllConversionsQualified": "0"}, + ], + "SearchQueryPerformanceReportRequest": [ + {"CampaignName": "Acme Plumbing - Search", "CampaignStatus": "Active", "AdGroupName": "Drains", + "AdGroupStatus": "Active", "SearchQuery": "plumber riverside", "Keyword": "plumber", "BidMatchType": "Broad", + "DeliveredMatchType": "Broad", "Impressions": "40", "Clicks": "6", "Spend": "51.00", "Ctr": "15.00%", + "AverageCpc": "8.50", "ConversionsQualified": "0", "Revenue": "0"}, + {"CampaignName": "Acme Plumbing - Search", "CampaignStatus": "Active", "AdGroupName": "Drains", + "AdGroupStatus": "Active", "SearchQuery": "drain cleaning springfield", "Keyword": "drain cleaning", + "BidMatchType": "Phrase", "DeliveredMatchType": "Broad", "Impressions": "30", "Clicks": "3", "Spend": "24.00", + "Ctr": "10.00%", "AverageCpc": "8.00", "ConversionsQualified": "1", + "Revenue": "0"}, + ], + "GeographicPerformanceReportRequest": [ + {"CampaignName": "Acme Plumbing - Search", "LocationType": "Physical location", "City": "Springfield", + "State": "California", "Country": "United States", "Impressions": "500", "Clicks": "20", "Spend": "150.00", + "ConversionsQualified": "0"}, + {"CampaignName": "Acme Plumbing - Search", "LocationType": "Location of interest", "City": "Los Angeles", + "State": "California", "Country": "United States", "Impressions": "100", "Clicks": "10", "Spend": "90.00", + "ConversionsQualified": "0"}, + ], +} + + +_DEPRECATED_COLUMNS = { + "Conversions", "ConversionRate", "CostPerConversion", + "AllConversions", "AllConversionRate", "AllCostPerConversion", +} + + +def _fake_api(extra: dict | None = None, reports: dict | None = None): + calls: list[tuple] = [] + submitted: dict[str, dict] = {} + reports = {**_REPORTS, **(reports or {})} + + def handle(config, service, path, body=None, *, method="POST", account_id="", customer_id="", mutation=False): + calls.append((service, path, body, method, account_id, customer_id)) + key = (service, path) + if extra and key in extra: + handler = extra[key] + if isinstance(handler, Exception): + raise handler + return handler(body) if callable(handler) else handler + if key == ("customer", "Account/Query"): + return _ACCOUNT + if key == ("campaign", "Campaigns/QueryByAccountId"): + return _CAMPAIGNS + if key == ("campaign", "CampaignCriterions/QueryByIds"): + return {"CampaignCriterions": _CRITERIONS.get((body["CampaignId"], body["CriterionType"]), [])} + if key == ("campaign", "AdGroups/QueryByCampaignId"): + return {"AdGroups": _AD_GROUPS.get(body["CampaignId"], [])} + if key == ("campaign", "Keywords/QueryByAdGroupId"): + return {"Keywords": _KEYWORDS.get(body["AdGroupId"], [])} + if key == ("campaign", "Ads/QueryByAdGroupId"): + return {"Ads": _ADS.get(body["AdGroupId"], [])} + if key == ("campaign", "UetTags/QueryByIds"): + return _TAGS + if key == ("campaign", "ConversionGoals/QueryByIds"): + return _GOALS + if key == ("reporting", "GenerateReport/Submit"): + rid = f"r{len(submitted) + 1}" + submitted[rid] = body["ReportRequest"] + return {"ReportRequestId": rid} + if key == ("reporting", "GenerateReport/Poll"): + rid = body["ReportRequestId"] + return {"ReportRequestStatus": {"Status": "Success", "ReportDownloadUrl": f"https://dl.example/{rid}"}} + if method == "PUT": + return {"PartialErrors": []} + raise AssertionError(f"unexpected Microsoft call {service} {path}") + + class _Download: + status_code = 200 + + def __init__(self, content): + self.content = content + + def download(url, timeout=None): + rid = url.rsplit("/", 1)[-1] + request = submitted[rid] + columns = request.get("Columns") or [] + # Like Microsoft: only the requested columns come back, and the + # deprecated conversion columns read 0. + rows = [ + {c: ("0" if c in _DEPRECATED_COLUMNS else r.get(c, "")) for c in columns} if columns else r + for r in reports.get(request["Type"], []) + ] + return _Download(_csv(rows)) + + ctx = _Patches( + patch("adloop.microsoft_ads.client.ms_request", side_effect=handle), + patch("requests.get", side_effect=download), + ) + return calls, submitted, ctx + + +class _Patches: + def __init__(self, *patches): + self.patches = patches + + def __enter__(self): + for p in self.patches: + p.__enter__() + return self + + def __exit__(self, *exc): + for p in reversed(self.patches): + p.__exit__(*exc) + + +# --------------------------------------------------------------------------- +# Config and OAuth +# --------------------------------------------------------------------------- + + +class TestConfig: + def test_block_parses(self, tmp_path): + path = tmp_path / "config.yaml" + path.write_text( + "microsoft_ads:\n developer_token: dt\n client_id: app\n customer_id: 900800700\n" + " ad_account_id: 100200300\n" + ) + cfg = load_config(str(path)).microsoft_ads + assert (cfg.developer_token, cfg.client_id, cfg.customer_id, cfg.ad_account_id) == ( + "dt", "app", "900800700", "100200300") + assert cfg.tenant == "common" and cfg.token_path.endswith("microsoft_token.json") + + +class _Resp: + def __init__(self, status: int, payload=None, headers=None, content=None): + self.status_code = status + self._payload = payload + self.headers = headers or {} + self.content = content if content is not None else (b"x" if payload is not None else b"") + + def json(self): + if self._payload is None: + raise ValueError("no body") + return self._payload + + +class TestAuth: + def test_missing_client_and_refresh_token(self): + with pytest.raises(MicrosoftAdsAuthError) as err: + MicrosoftCredentials(client_id="", refresh_token="x") + assert err.value.error_code == "missing_client" + with pytest.raises(MicrosoftAdsAuthError) as err: + MicrosoftCredentials(client_id="app", refresh_token="") + assert "adloop microsoft-login" in str(err.value) + + def test_refresh_rotates_and_persists_the_token(self, tmp_path): + path = tmp_path / "ms.json" + creds = auth.FileMicrosoftCredentials(token_path=path, client_id="app", refresh_token="old") + reply = {"access_token": "new-at", "refresh_token": "new-rt", "expires_in": 3600} + with patch("requests.post", return_value=_Resp(200, reply)) as post: + assert creds.token() == "new-at" + sent = post.call_args.kwargs["data"] + assert sent["grant_type"] == "refresh_token" and sent["scope"] == auth.SCOPE + stored = json.loads(path.read_text()) + assert stored["refresh_token"] == "new-rt" + assert stat.S_IMODE(os.stat(path).st_mode) == 0o600 + + def test_invalid_grant_says_sign_in_again(self, tmp_path): + creds = auth.FileMicrosoftCredentials(token_path=tmp_path / "t.json", client_id="app", refresh_token="old") + with patch("requests.post", return_value=_Resp(400, {"error": "invalid_grant"})): + with pytest.raises(MicrosoftAdsAuthError) as err: + creds.token() + assert err.value.error_code == "invalid_grant" and "microsoft-login" in str(err.value) + + def test_device_code_login_waits_then_stores(self, tmp_path): + cfg = AdLoopConfig(microsoft_ads=MicrosoftAdsConfig(client_id="app", token_path=str(tmp_path / "ms.json"))) + replies = [ + _Resp(200, {"device_code": "dc", "user_code": "ABCD", "verification_uri": "https://microsoft.com/devicelogin", + "interval": 1, "expires_in": 60, "message": "Go to the page and enter ABCD."}), + _Resp(400, {"error": "authorization_pending"}), + _Resp(200, {"access_token": "at", "refresh_token": "rt", "expires_in": 3600}), + ] + said: list[str] = [] + with patch("requests.post", side_effect=replies): + path = auth.device_code_login(cfg, say=said.append, sleep=lambda s: None) + assert json.loads(path.read_text())["refresh_token"] == "rt" + assert "ABCD" in said[0] + + def test_local_credentials_read_the_token_file(self, tmp_path): + path = tmp_path / "ms.json" + path.write_text(json.dumps({"refresh_token": "rt", "access_token": "at", "expires_at": 10**12})) + cfg = AdLoopConfig(microsoft_ads=MicrosoftAdsConfig(client_id="app", token_path=str(path))) + creds = auth.local_credentials(cfg) + assert creds.token() == "at" + + +# --------------------------------------------------------------------------- +# Client +# --------------------------------------------------------------------------- + + +class TestClient: + def test_headers_and_body(self, creds): + with patch("requests.request", return_value=_Resp(200, {"Campaigns": []})) as req: + client.campaign_request(_config(), "Campaigns/QueryByAccountId", {"AccountId": ACCOUNT}, + account_id=ACCOUNT, customer_id=CUSTOMER) + args, kwargs = req.call_args + assert args == ("POST", client.HOSTS["campaign"] + "/Campaigns/QueryByAccountId") + headers = kwargs["headers"] + assert headers["Authorization"] == "Bearer at-1" + assert headers["DeveloperToken"] == "dev-token" + assert headers["CustomerId"] == CUSTOMER and headers["CustomerAccountId"] == ACCOUNT + assert kwargs["json"] == {"AccountId": ACCOUNT} + + def test_missing_developer_token(self, creds): + cfg = AdLoopConfig(microsoft_ads=MicrosoftAdsConfig(client_id="app")) + with pytest.raises(MicrosoftAdsAuthError) as err: + client.ms_request(cfg, "customer", "User/Query", {}) + assert err.value.error_code == "missing_developer_token" + + def test_expired_token_is_refreshed_once(self, creds): + expired = _Resp(400, {"Type": "AdApiFaultDetail", "Errors": [{"Code": 109, "ErrorCode": "AuthenticationTokenExpired", + "Message": "expired"}]}) + with patch("requests.request", side_effect=[expired, _Resp(200, {"ok": True})]) as req: + assert client.ms_request(_config(), "customer", "User/Query", {}) == {"ok": True} + assert creds.refreshes == 1 + assert req.call_args.kwargs["headers"]["Authorization"] == "Bearer at-2" + + def test_operation_errors_are_reported(self, creds): + fault = {"Type": "ApiFaultDetail", "TrackingId": "trk-1", + "OperationErrors": [{"Code": 1100, "ErrorCode": "CampaignServiceInvalidAccountId", + "Message": "The account ID is invalid."}]} + with patch("requests.request", return_value=_Resp(400, fault)): + with pytest.raises(MicrosoftAdsApiError) as err: + client.campaign_request(_config(), "Campaigns/QueryByAccountId", {}, account_id="1") + assert "CampaignServiceInvalidAccountId: The account ID is invalid." in str(err.value) + assert "trk-1" in str(err.value) and "1100" in err.value.codes + + def test_throttling_waits_briefly(self, creds): + throttled = _Resp(400, {"Errors": [{"Code": 117, "ErrorCode": "CallRateExceeded", "Message": "slow down"}]}, + headers={"Retry-After": "2"}) + with patch("requests.request", side_effect=[throttled, _Resp(200, {"ok": 1})]), patch("time.sleep") as sleep: + assert client.ms_request(_config(), "customer", "User/Query", {}) == {"ok": 1} + sleep.assert_called_once_with(2) + + def test_report_runner_polls_and_parses(self, creds): + responses = iter([ + {"ReportRequestId": "r1"}, + {"ReportRequestStatus": {"Status": "Pending"}}, + {"ReportRequestStatus": {"Status": "Success", "ReportDownloadUrl": "https://dl/r1"}}, + ]) + + class _Dl: + status_code = 200 + content = _csv([{"CampaignName": "A", "Clicks": "3"}]) + + with patch("adloop.microsoft_ads.client.ms_request", side_effect=lambda *a, **k: next(responses)) as req, \ + patch("requests.get", return_value=_Dl()): + rows = client.run_report(_config(), {"Type": "CampaignPerformanceReportRequest"}, + account_id=ACCOUNT, sleep=lambda s: None) + assert rows == [{"CampaignName": "A", "Clicks": "3"}] + submitted = req.call_args_list[0].args[3]["ReportRequest"] + assert submitted["Format"] == "Csv" and submitted["ExcludeReportHeader"] is True + + def test_report_without_rows_has_no_file(self, creds): + responses = iter([{"ReportRequestId": "r1"}, {"ReportRequestStatus": {"Status": "Success"}}]) + with patch("adloop.microsoft_ads.client.ms_request", side_effect=lambda *a, **k: next(responses)): + assert client.run_report(_config(), {"Type": "X"}, account_id=ACCOUNT, sleep=lambda s: None) == [] + + def test_parse_csv_skips_footer_and_bom(self): + data = ("CampaignName,Clicks\nA,3\n\"©2026 Microsoft Corporation. All rights reserved. \",\n").encode() + assert client.parse_csv(data) == [{"CampaignName": "A", "Clicks": "3"}] + + +# --------------------------------------------------------------------------- +# Reads +# --------------------------------------------------------------------------- + + +class TestReads: + def test_accounts(self): + _, _, ctx = _fake_api({ + ("customer", "User/Query"): {"User": {"Id": 5, "UserName": "ads@x", "ContactInfo": {"Email": "a@x"}}, + "CustomerRoles": [{"CustomerId": CUSTOMER, "RoleId": 41, "AccountIds": None}]}, + ("customer", "Accounts/Search"): {"Accounts": [_ACCOUNT["Account"]]}, + }) + with ctx: + result = read.list_microsoft_ads_accounts(_config()) + assert result["total"] == 1 + assert result["accounts"][0] == { + "ad_account_id": ACCOUNT, "name": "Acme Plumbing", "number": "X0000AAA", "customer_id": CUSTOMER, + "currency": "USD", "time_zone": "PacificTimeUSCanadaTijuana", "status": "Active", "pause_reason": None, + } + + def test_campaigns_with_location_targeting(self): + _, _, ctx = _fake_api() + with ctx: + result = read.get_microsoft_campaigns(_config()) + core = result["campaigns"][0] + assert core["daily_budget"] == 35.0 and core["bidding"] == {"strategy": "MaxClicks", "max_cpc": 9.0} + assert core["locations"]["included"] == ["62704 (PostalCode)"] + assert core["locations"]["excluded"] == ["Chatham (City)"] + assert core["locations"]["intent"] == "PeopleInOrSearchingForOrViewingPages" + shared = result["campaigns"][1] + assert shared["shared_budget_id"] == "777" + joined = " ".join(result["insights"]) + assert "'PeopleIn' keeps clicks local" in joined + assert "shared budget 777" in joined + + def test_paused_account_is_flagged(self): + paused = {"Account": dict(_ACCOUNT["Account"], AccountLifeCycleStatus="Pause", PauseReason=4)} + _, _, ctx = _fake_api({("customer", "Account/Query"): paused}) + with ctx: + result = read.get_microsoft_campaigns(_config(), include_targeting=False) + assert any("account is Pause" in i for i in result["insights"]) + + def test_ad_groups_flag_partners_and_audience_network(self): + _, _, ctx = _fake_api() + with ctx: + result = read.get_microsoft_ad_groups(_config()) + drains = result["ad_groups"][0] + assert drains["cpc_bid"] == 4.5 and drains["campaign_status"] == "Active" + joined = " ".join(result["insights"]) + assert "syndicated search partners" in joined and "Audience Network" in joined + + def test_keywords_flag_disapproved_and_broad_manual(self): + manual = {"Campaigns": [dict(_CAMPAIGNS["Campaigns"][0], BiddingScheme={"Type": "ManualCpcBiddingScheme"})]} + _, _, ctx = _fake_api({("campaign", "Campaigns/QueryByAccountId"): manual}) + with ctx: + result = read.get_microsoft_keywords(_config()) + assert result["total_keywords"] == 3 + joined = " ".join(result["insights"]) + assert "'plumber'" in joined and "broad-match" in joined + + def test_ads_texts_and_groups_without_active_ads(self): + _, _, ctx = _fake_api() + with ctx: + result = read.get_microsoft_ads(_config()) + ad = result["ads"][0] + assert ad["headlines"] == ["Drain Cleaning $69 [pinned Headline1]", "Springfield Plumber"] + assert ad["final_urls"] == ["https://example.com/drain"] + assert any("no active ad" in i for i in result["insights"]) + + def test_campaign_performance_report(self): + _, submitted, ctx = _fake_api() + with ctx: + result = read.get_microsoft_performance(_config(), date_range_start="2026-10-01", date_range_end="2026-10-31") + request = submitted["r1"] + assert request["Type"] == "CampaignPerformanceReportRequest" + assert request["Aggregation"] == "Summary" + assert "ImpressionLostToBudgetPercent" in request["Columns"] + assert request["Time"] == { + "CustomDateRangeStart": {"Day": 1, "Month": 10, "Year": 2026}, + "CustomDateRangeEnd": {"Day": 31, "Month": 10, "Year": 2026}, + "ReportTimeZone": "PacificTimeUSCanadaTijuana", + } + assert request["Scope"] == {"AccountIds": [ACCOUNT]} + row = result["rows"][0] + assert row["clicks"] == 45 and row["impressions"] == 1200 and row["spend"] == 382.1 + assert row["ctr"] == 0.0375 and row["lost_to_budget_pct"] == 41.2 + assert row["campaign_status"] == "Active" + joined = " ".join(result["insights"]) + assert "zero conversions" in joined + + def test_daily_breakdown_and_bad_level(self): + _, submitted, ctx = _fake_api(reports={"AdGroupPerformanceReportRequest": []}) + with ctx: + result = read.get_microsoft_performance(_config(), level="ad_group", breakdown="date", campaign_id="500100200") + request = submitted["r1"] + assert request["Aggregation"] == "Daily" and request["Columns"][0] == "TimePeriod" + assert request["Scope"] == {"Campaigns": [{"AccountId": ACCOUNT, "CampaignId": "500100200"}]} + assert result["insights"] == ["No delivery in this window."] + with pytest.raises(ValueError): + read.get_microsoft_performance(_config(), level="search_term") + + def test_search_terms_compact(self): + _, _, ctx = _fake_api() + with ctx: + result = read.get_microsoft_search_terms(_config(), compact=True) + assert result["waste_candidates"][0]["search_term"] == "plumber riverside" + assert result["top_converters"][0]["search_term"] == "drain cleaning springfield" + joined = " ".join(result["insights"]) + assert "negative keyword candidates" in joined and "close variants" in joined + + def test_location_report_flags_interest_traffic(self): + _, _, ctx = _fake_api() + with ctx: + result = read.get_microsoft_location_performance(_config()) + assert result["totals"]["spend_from_location_of_interest"] == 90.0 + assert any("location of interest" in i for i in result["insights"]) + + def test_location_report_never_repeats_a_column(self): + _, submitted, ctx = _fake_api() + with ctx: + read.get_microsoft_location_performance(_config(), group_by="state") + columns = submitted["r1"]["Columns"] + assert len(columns) == len(set(columns)) + + def test_conversion_setup_verdict(self): + _, _, ctx = _fake_api() + with ctx: + result = read.get_microsoft_conversion_setup(_config(), min_clicks=30) + assert result["verdict"] == "broken" + by_check = {c["check"]: c for c in result["checks"]} + assert by_check["uet tag 'Main site' (400500600)"]["status"] == "fail" + assert by_check["goal 'Thank you page'"]["status"] == "fail" + assert "excluded from bidding" in by_check["goal 'Thank you page'"]["detail"] + assert by_check["goal 'Web Form Lead'"]["status"] == "warn" + assert by_check["campaign 'Acme Plumbing - Search' conversions"]["status"] == "warn" + + def test_window_rejects_future_and_inverted_dates(self): + future = (date.today() + timedelta(days=3)).isoformat() + with pytest.raises(ValueError): + read.report_window("", future, "PacificTimeUSCanadaTijuana") + with pytest.raises(ValueError): + read.report_window("2026-10-10", "2026-10-01", "PacificTimeUSCanadaTijuana") + + +# --------------------------------------------------------------------------- +# Writes and the apply gate +# --------------------------------------------------------------------------- + + +class TestWrites: + def test_pause_keyword_finds_its_parents(self): + _, _, ctx = _fake_api() + with ctx: + preview = write.draft_microsoft_status(_config(), action="pause", entity_type="keyword", entity_id="101") + assert preview["platform"] == "microsoft" + changes = preview["changes"] + assert changes["name"] == "drain cleaning [Phrase]" + assert changes["ad_group_id"] == "11" and changes["campaign_id"] == "500100200" + assert changes["current_status"] == "Active" and changes["target_status"] == "Paused" + + def test_enable_warns_about_paused_parent(self): + _, _, ctx = _fake_api() + with ctx: + preview = write.draft_microsoft_status(_config(), action="enable", entity_type="keyword", entity_id="103") + assert any("'Water heaters' is Paused" in w for w in preview["warnings"]) + + def test_unknown_entity(self): + _, _, ctx = _fake_api() + with ctx: + result = write.draft_microsoft_status(_config(), action="pause", entity_type="ad", entity_id="999") + assert "was not found" in result["error"] + + def test_budget_draft_guards(self): + _, _, ctx = _fake_api() + with ctx: + shared = write.draft_microsoft_campaign_budget(_config(), campaign_id="600", daily_budget=40) + capped = write.draft_microsoft_campaign_budget(_config(max_daily_budget=30), campaign_id="500100200", + daily_budget=40) + ok = write.draft_microsoft_campaign_budget(_config(), campaign_id="500100200", daily_budget=40) + assert "shared budget 777" in shared["error"] + assert "error" in capped + assert ok["changes"]["current_daily_budget"] == 35.0 and ok["changes"]["new_daily_budget"] == 40.0 + assert any("1216.0" in w for w in ok["warnings"]) + + def test_confirm_and_apply_dry_run_then_apply(self): + from adloop.ads import write as ads_write + + calls, _, ctx = _fake_api() + with ctx: + plan_id = write.draft_microsoft_campaign_budget(_config(), campaign_id="500100200", daily_budget=40)["plan_id"] + dry = ads_write.confirm_and_apply(_config(), plan_id=plan_id, dry_run=True) + assert dry["status"] == "DRY_RUN_SUCCESS" and dry["checks"]["budget_cap_ok"] is True + assert "Microsoft Advertising has no validate-only mode" in dry["note"] + result = ads_write.confirm_and_apply(_config(), plan_id=plan_id, dry_run=False) + assert result["status"] == "APPLIED" + put = [c for c in calls if c[3] == "PUT"] + assert put == [("campaign", "Campaigns", + {"AccountId": ACCOUNT, "Campaigns": [{"Id": "500100200", "DailyBudget": 40.0}]}, + "PUT", ACCOUNT, CUSTOMER)] + + def test_dry_run_refuses_a_budget_changed_since_the_draft(self): + from adloop.ads import write as ads_write + + _, _, ctx = _fake_api() + with ctx: + plan_id = write.draft_microsoft_campaign_budget(_config(), campaign_id="500100200", daily_budget=40)["plan_id"] + moved = {"Campaigns": [dict(_CAMPAIGNS["Campaigns"][0], DailyBudget=45.0)]} + _, _, ctx = _fake_api({("campaign", "Campaigns/QueryByAccountId"): moved}) + with ctx: + dry = ads_write.confirm_and_apply(_config(), plan_id=plan_id, dry_run=True) + assert dry["status"] == "DRY_RUN_FAILED" and "changed since the draft" in dry["error"] + + def test_status_apply_sends_the_ad_type_and_reports_partial_errors(self): + _, _, ctx = _fake_api() + with ctx: + preview = write.draft_microsoft_status(_config(), action="pause", entity_type="ad", entity_id="201") + plan = preview_store.get_plan(preview["plan_id"]) + failing = {"PartialErrors": [{"Index": 0, "Code": 1, "ErrorCode": "InvalidStatus", "Message": "nope"}]} + calls, _, ctx = _fake_api({("campaign", "Ads"): failing}) + with ctx, pytest.raises(MicrosoftAdsApiError) as err: + write.apply_plan(_config(), plan) + assert "InvalidStatus: nope" in str(err.value) + body = [c for c in calls if c[1] == "Ads"][0][2] + assert body == {"AdGroupId": "11", "Ads": [{"Id": "201", "Status": "Paused", "Type": "ResponsiveSearch"}]} + + +class TestReviewFixes: + """Findings from the Codex review: each test pins one of them.""" + + # -- #1: the real apply re-checks what the dry run checked ------------- + + def _drafted_budget(self): + _, _, ctx = _fake_api() + with ctx: + return write.draft_microsoft_campaign_budget(_config(), campaign_id="500100200", daily_budget=40)["plan_id"] + + def test_apply_refuses_a_budget_changed_after_the_dry_run(self): + from adloop.ads import write as ads_write + + plan_id = self._drafted_budget() + _, _, ctx = _fake_api() + with ctx: + assert ads_write.confirm_and_apply(_config(), plan_id=plan_id, dry_run=True)["status"] == "DRY_RUN_SUCCESS" + moved = {"Campaigns": [dict(_CAMPAIGNS["Campaigns"][0], DailyBudget=45.0)]} + calls, _, ctx = _fake_api({("campaign", "Campaigns/QueryByAccountId"): moved}) + with ctx: + result = ads_write.confirm_and_apply(_config(), plan_id=plan_id, dry_run=False) + assert "changed since the draft" in result["error"] + assert not [c for c in calls if c[3] == "PUT"] + # Nothing was sent, so the plan stays available. + assert preview_store.get_plan(plan_id) is not None + + def test_apply_refuses_a_campaign_moved_to_a_shared_budget(self): + plan = preview_store.get_plan(self._drafted_budget()) + shared = {"Campaigns": [dict(_CAMPAIGNS["Campaigns"][0], BudgetId=777)]} + calls, _, ctx = _fake_api({("campaign", "Campaigns/QueryByAccountId"): shared}) + with ctx, pytest.raises(ValueError, match="shared budget"): + write.apply_plan(_config(), plan) + assert not [c for c in calls if c[3] == "PUT"] + + def test_apply_rechecks_the_budget_cap(self): + from adloop.safety.guards import SafetyViolation + + plan = preview_store.get_plan(self._drafted_budget()) + calls, _, ctx = _fake_api() + with ctx, pytest.raises(SafetyViolation): + write.apply_plan(_config(max_daily_budget=30), plan) + assert not [c for c in calls if c[3] == "PUT"] + + def test_apply_refuses_a_status_changed_since_the_draft(self): + _, _, ctx = _fake_api() + with ctx: + plan = preview_store.get_plan( + write.draft_microsoft_status(_config(), action="pause", entity_type="campaign", entity_id="500100200")["plan_id"] + ) + paused = {"Campaigns": [dict(_CAMPAIGNS["Campaigns"][0], Status="Paused")]} + calls, _, ctx = _fake_api({("campaign", "Campaigns/QueryByAccountId"): paused}) + with ctx, pytest.raises(ValueError, match="status changed since the draft"): + write.apply_plan(_config(), plan) + assert not [c for c in calls if c[3] == "PUT"] + + def test_preview_names_the_entity_for_the_approval_card(self): + _, _, ctx = _fake_api() + with ctx: + preview = write.draft_microsoft_status(_config(), action="pause", entity_type="keyword", entity_id="101") + assert preview["changes"]["entity_name"] == "drain cleaning [Phrase]" + + # -- #2: qualified conversion columns ------------------------------------ + + def test_reports_ask_for_qualified_conversions_only(self): + keyword_rows = [{ + "CampaignName": "Acme Plumbing - Search", "CampaignStatus": "Active", "AdGroupId": "11", + "AdGroupName": "Drains", "AdGroupStatus": "Active", "KeywordId": "101", "Keyword": "drain cleaning", + "KeywordStatus": "Active", "BidMatchType": "Phrase", "QualityScore": "7", "Impressions": "100", + "Clicks": "10", "Spend": "80.00", "Ctr": "10.00%", "AverageCpc": "8.00", + "ConversionsQualified": "2", "Revenue": "0", + }] + _, submitted, ctx = _fake_api(reports={"KeywordPerformanceReportRequest": keyword_rows}) + with ctx: + result = read.get_microsoft_performance(_config(), level="keyword") + read.get_microsoft_search_terms(_config()) + read.get_microsoft_location_performance(_config()) + read.get_microsoft_conversion_setup(_config()) + for request in submitted.values(): + assert not set(request["Columns"]) & _DEPRECATED_COLUMNS, request["Type"] + row = result["rows"][0] + assert row["conversions"] == 2 and row["conversion_rate"] == 0.2 and row["cpa"] == 40.0 + + # -- #3: report scope ------------------------------------------------------ + + def test_campaign_scope_leaves_the_account_out(self): + _, submitted, ctx = _fake_api() + with ctx: + read.get_microsoft_search_terms(_config(), campaign_id="500100200") + assert submitted["r1"]["Scope"] == {"Campaigns": [{"AccountId": ACCOUNT, "CampaignId": "500100200"}]} + + def test_account_level_refuses_a_campaign_id(self): + with pytest.raises(ValueError, match="whole account"): + read.get_microsoft_performance(_config(), level="account", campaign_id="500100200") + + # -- #5: no signed URL in errors ----------------------------------------- + + def _report_until_download(self, download): + responses = iter([ + {"ReportRequestId": "r1"}, + {"ReportRequestStatus": {"Status": "Success", + "ReportDownloadUrl": "https://dl.example/r1?sig=SECRET-SIGNATURE"}}, + ]) + with patch("adloop.microsoft_ads.client.ms_request", side_effect=lambda *a, **k: next(responses)), \ + patch("requests.get", side_effect=download), pytest.raises(MicrosoftAdsApiError) as err: + client.run_report(_config(), {"Type": "CampaignPerformanceReportRequest"}, + account_id=ACCOUNT, sleep=lambda _s: None) + return err.value + + def test_download_transport_error_hides_the_signed_url(self): + import requests + + def boom(url, timeout=None): + raise requests.ConnectionError(f"Max retries exceeded with url: {url}") + + err = self._report_until_download(boom) + assert "SECRET-SIGNATURE" not in str(err) and "dl.example" not in str(err) + assert err.__cause__ is None and err.__suppress_context__ + + def test_download_http_error_hides_the_signed_url(self): + class _Forbidden: + status_code = 403 + content = b"" + + err = self._report_until_download(lambda url, timeout=None: _Forbidden()) + assert err.status == 403 and "SECRET-SIGNATURE" not in str(err) and "dl.example" not in str(err) + + def test_api_transport_error_is_wrapped(self, creds): + import requests + + with patch("adloop.microsoft_ads.client._credentials", return_value=creds), \ + patch("requests.request", side_effect=requests.Timeout("read timed out")), \ + pytest.raises(MicrosoftAdsApiError, match="Could not reach Microsoft Advertising"): + client.campaign_request(_config(), "Campaigns/QueryByAccountId", {}, account_id=ACCOUNT) + + # -- #9: UET only where a goal needs it ---------------------------------- + + def test_offline_only_goals_need_no_tag(self): + offline = {"ConversionGoals": [ + {"Id": "20", "Name": "Booked jobs", "Type": "OfflineConversion", "Status": "Active", + "TrackingStatus": "RecordingConversions", "ExcludeFromBidding": False}, + ]} + _, _, ctx = _fake_api({ + ("campaign", "UetTags/QueryByIds"): {"UetTags": []}, + ("campaign", "ConversionGoals/QueryByIds"): offline, + }) + with ctx: + result = read.get_microsoft_conversion_setup(_config()) + tag = next(c for c in result["checks"] if c["check"] == "uet tag") + assert tag["status"] == "info" + assert result["verdict"] != "broken" + + def test_unused_unverified_tag_only_warns(self): + tags = {"UetTags": [ + {"Id": "1", "Name": "Main", "TrackingStatus": "Active"}, + {"Id": "2", "Name": "Old agency tag", "TrackingStatus": "Unverified"}, + ]} + goals = {"ConversionGoals": [ + {"Id": "9", "Name": "Web Form Lead", "Type": "Event", "Status": "Active", "TagId": "1", + "TrackingStatus": "RecordingConversions", "ExcludeFromBidding": False}, + ]} + _, _, ctx = _fake_api({ + ("campaign", "UetTags/QueryByIds"): tags, + ("campaign", "ConversionGoals/QueryByIds"): goals, + }) + with ctx: + result = read.get_microsoft_conversion_setup(_config()) + by_check = {c["check"]: c for c in result["checks"]} + assert by_check["uet tag 'Main' (1)"]["status"] == "pass" + assert "Used by 'Web Form Lead'" in by_check["uet tag 'Main' (1)"]["detail"] + old = by_check["uet tag 'Old agency tag' (2)"] + assert old["status"] == "warn" and "No active goal uses this tag" in old["detail"] + + def test_tag_an_event_goal_depends_on_fails(self): + _, _, ctx = _fake_api() + with ctx: + result = read.get_microsoft_conversion_setup(_config()) + tag = next(c for c in result["checks"] if c["check"] == "uet tag 'Main site' (400500600)") + assert tag["status"] == "fail" and "Web Form Lead" in tag["detail"] + + def test_setup_and_campaigns_ask_for_campaign_goals(self): + calls, _, ctx = _fake_api() + with ctx: + read.get_microsoft_conversion_setup(_config()) + read.get_microsoft_campaigns(_config(), include_targeting=False) + bodies = [c[2] for c in calls if c[1] == "Campaigns/QueryByAccountId"] + assert bodies and all("CampaignConversionGoal" in b.get("ReturnAdditionalFields", "").split(", ") for b in bodies) + + # -- #4: approval card --------------------------------------------------- + + def test_approval_card_labels_microsoft_plans(self): + from pathlib import Path + + import adloop.safety as safety_pkg + + html = (Path(safety_pkg.__file__).parent / "approval_card.html").read_text() + assert 'microsoft: "Microsoft Advertising"' in html + assert 'op.startsWith("microsoft_")' in html + + +class TestServer: + def test_missing_developer_token_gets_a_hint(self): + from adloop import runtime, server + + runtime.set_default_config(AdLoopConfig(microsoft_ads=MicrosoftAdsConfig(client_id="app", ad_account_id="1"))) + try: + with patch("adloop.microsoft_ads.client._credentials", return_value=_Creds()): + result = server.get_microsoft_campaigns() + finally: + runtime.set_default_config(None) + assert result["auth_error"] == "MICROSOFT_ADS_MISSING_DEVELOPER_TOKEN" + assert "developers.ads.microsoft.com" in result["hint"] + + def test_health_check_without_microsoft(self, monkeypatch): + import adloop.ads.gaql as gaql + import adloop.ga4.reports as reports + from adloop import runtime, server + + monkeypatch.setattr(gaql, "execute_query", lambda *_a, **_k: []) + monkeypatch.setattr(reports, "get_account_summaries", lambda _c: {"accounts": [], "total_properties": 0}) + runtime.set_default_config(AdLoopConfig()) + try: + status = server.health_check() + finally: + runtime.set_default_config(None) + assert status["microsoft_ads"] == "not_configured" + + def test_health_check_reports_the_account(self, monkeypatch): + import adloop.ads.gaql as gaql + import adloop.ga4.reports as reports + from adloop import runtime, server + + monkeypatch.setattr(gaql, "execute_query", lambda *_a, **_k: []) + monkeypatch.setattr(reports, "get_account_summaries", lambda _c: {"accounts": [], "total_properties": 0}) + runtime.set_default_config(_config()) + _, _, ctx = _fake_api() + try: + with ctx: + status = server.health_check() + finally: + runtime.set_default_config(None) + assert status["microsoft_ads"] == "ok" and status["microsoft_ads_account"] == ACCOUNT + + +class TestReviewFindingsRoundTwo: + def test_budget_blocked_after_the_dry_run_cannot_apply(self): + # Finding 1: draft, dry-run, then block the operation: the apply refuses. + from adloop.ads import write as ads_write + + calls, _, ctx = _fake_api() + cfg = _config() + with ctx: + plan_id = write.draft_microsoft_campaign_budget(cfg, campaign_id="500100200", daily_budget=40)["plan_id"] + assert ads_write.confirm_and_apply(cfg, plan_id=plan_id, dry_run=True)["status"] == "DRY_RUN_SUCCESS" + cfg.safety.blocked_operations = ["microsoft_update_campaign_budget"] + result = ads_write.confirm_and_apply(cfg, plan_id=plan_id, dry_run=False) + assert result["status"] == "BLOCKED" and not [c for c in calls if c[3] == "PUT"] + + def test_status_dialog_shows_the_target_status(self): + # Finding 2: the requested status must not hide behind "more fields". + from adloop.safety.approval import confirmation_message + + _, _, ctx = _fake_api() + with ctx: + preview = write.draft_microsoft_status(_config(), action="pause", entity_type="keyword", entity_id="101") + message = confirmation_message(preview_store.get_plan(preview["plan_id"])) + lines = message.splitlines() + assert "- target status: Paused" in lines and "- current status: Active" in lines + assert "more fields" not in message + assert sum(1 for l in lines if "drain cleaning [Phrase]" in l) == 1 # no duplicate name line + + def test_token_errors_never_echo_credentials(self): + creds = auth.MicrosoftCredentials(client_id="app", client_secret="ms-secret-xyz", refresh_token="rt-abcdef") + echo = {"error": "invalid_grant", "error_description": "refresh token rt-abcdef rejected for ms-secret-xyz"} + with patch("adloop.microsoft_ads.auth._post_form", return_value=(400, echo)), \ + pytest.raises(MicrosoftAdsAuthError) as err: + creds.token() + assert "rt-abcdef" not in str(err.value) and "ms-secret-xyz" not in str(err.value) + + +class TestBrowserLogin: + """`adloop microsoft-login` signs in in the browser: security defaults block device code (530035).""" + + def _cfg(self, tmp_path): + return AdLoopConfig(microsoft_ads=MicrosoftAdsConfig( + developer_token="dt", client_id="app-client-id", token_path=str(tmp_path / "ms_token.json"))) + + def test_authorization_code_with_pkce_end_to_end(self, tmp_path): + import base64 + import hashlib + from urllib.parse import parse_qs, urlsplit + + opened: list[str] = [] + + def listen(uri): + assert uri == "http://localhost:8080/callback" + query = parse_qs(urlsplit(opened[0]).query) + return {"code": "auth-code-1", "state": query["state"][0]} + + with patch("adloop.microsoft_ads.auth._post_form", return_value=(200, { + "access_token": "at", "refresh_token": "rt-new", "expires_in": 3600, "scope": auth.SCOPE, + })) as post: + path = auth.browser_login(self._cfg(tmp_path), login_hint="ads@contoso.onmicrosoft.com", + say=lambda _m: None, open_browser=opened.append, listen=listen) + url = urlsplit(opened[0]) + query = parse_qs(url.query) + assert url.netloc == "login.microsoftonline.com" and url.path == "/common/oauth2/v2.0/authorize" + assert query["client_id"] == ["app-client-id"] and query["response_type"] == ["code"] + assert query["redirect_uri"] == ["http://localhost:8080/callback"] + assert query["scope"] == [auth.SCOPE] and query["code_challenge_method"] == ["S256"] + assert query["login_hint"] == ["ads@contoso.onmicrosoft.com"] and query["prompt"] == ["select_account"] + form = post.call_args.args[1] + assert post.call_args.args[0].endswith("/common/oauth2/v2.0/token") + assert form["grant_type"] == "authorization_code" and form["code"] == "auth-code-1" + assert form["redirect_uri"] == "http://localhost:8080/callback" + # The verifier sent at the token step matches the challenge sent at authorize. + challenge = base64.urlsafe_b64encode(hashlib.sha256(form["code_verifier"].encode()).digest()).decode().rstrip("=") + assert challenge == query["code_challenge"][0] + saved = json.loads(path.read_text()) + assert saved["refresh_token"] == "rt-new" and stat.S_IMODE(os.stat(path).st_mode) == 0o600 + + def test_state_mismatch_and_provider_errors(self, tmp_path): + with patch("adloop.microsoft_ads.auth._post_form") as post, pytest.raises(MicrosoftAdsAuthError) as err: + auth.browser_login(self._cfg(tmp_path), say=lambda _m: None, open_browser=lambda _u: None, + listen=lambda _u: {"code": "c", "state": "forged"}) + assert err.value.error_code == "state_mismatch" and not post.called + with pytest.raises(MicrosoftAdsAuthError) as err: + auth.browser_login(self._cfg(tmp_path), say=lambda _m: None, open_browser=lambda _u: None, + listen=lambda _u: {"error": "access_denied", + "error_description": "AADSTS530035: blocked by security defaults"}) + assert err.value.error_code == "access_denied" and "530035" in str(err.value) + + def test_refused_code_redacts_it(self, tmp_path): + from urllib.parse import parse_qs, urlsplit + + opened: list[str] = [] + listen = lambda _u: {"code": "secret-code-123", "state": parse_qs(urlsplit(opened[0]).query)["state"][0]} # noqa: E731 + echo = {"error": "invalid_grant", "error_description": "code secret-code-123 was already redeemed"} + with patch("adloop.microsoft_ads.auth._post_form", return_value=(400, echo)), \ + pytest.raises(MicrosoftAdsAuthError) as err: + auth.browser_login(self._cfg(tmp_path), say=lambda _m: None, open_browser=opened.append, listen=listen) + assert "secret-code-123" not in str(err.value) + + def test_real_listener_receives_the_redirect(self, tmp_path): + import socket + import threading + + import requests + + from adloop.oauth_redirect import listen_once + + with socket.socket() as sock: + sock.bind(("127.0.0.1", 0)) + port = sock.getsockname()[1] + uri = f"http://127.0.0.1:{port}/callback" + got: dict = {} + worker = threading.Thread(target=lambda: got.update(listen_once(uri, 10, provider="Microsoft Advertising"))) + worker.start() + for _ in range(50): + try: + response = requests.get(f"{uri}?code=abc&state=xyz", timeout=2) + break + except requests.ConnectionError: + import time as _t + + _t.sleep(0.05) + worker.join(timeout=10) + assert got == {"code": "abc", "state": "xyz"} and "Microsoft Advertising sign-in" in response.text + + def test_cli_defaults_to_the_browser_and_keeps_device_code(self, tmp_path, monkeypatch, capsys): + import adloop + + calls = [] + monkeypatch.setattr("adloop.microsoft_ads.auth.browser_login", + lambda config, login_hint="": calls.append(("browser", login_hint)) or tmp_path / "t.json") + monkeypatch.setattr("adloop.microsoft_ads.auth.device_code_login", + lambda config: calls.append(("device", "")) or tmp_path / "t.json") + monkeypatch.setattr("adloop.config.load_config", lambda *a, **k: AdLoopConfig()) + monkeypatch.setattr("sys.argv", ["adloop", "microsoft-login", "--user", "ads@x.com"]) + adloop.main() + monkeypatch.setattr("sys.argv", ["adloop", "microsoft-login", "--device-code"]) + adloop.main() + assert calls == [("browser", "ads@x.com"), ("device", "")] + + +class TestUpstreamAuditFindings: + """Codex audit of the upstream ports (adloop-audit-2026-11-04-upstream.md), Microsoft read side.""" + + def test_api_errors_never_carry_credentials(self): + # Finding 10: a fault that echoes the request must not leak a token. + cfg = AdLoopConfig(microsoft_ads=MicrosoftAdsConfig( + developer_token="developer-token-123456", client_id="app-id", client_secret="client-secret-abcdef", + customer_id=CUSTOMER, ad_account_id=ACCOUNT)) + creds = _Creds() + creds.refresh_token, creds.access_token = "refresh-token-987654", "access-token-555555" + echo = {"Errors": [{"Code": 1001, "ErrorCode": "CampaignServiceInvalidRequest", + "Message": "Bearer access-token-555555 / developer-token-123456 / " + "client-secret-abcdef / refresh-token-987654"}]} + with patch("adloop.microsoft_ads.client._credentials", return_value=creds), \ + patch("requests.request", return_value=_Resp(400, echo)), \ + pytest.raises(MicrosoftAdsApiError) as err: + client.campaign_request(cfg, "Campaigns/QueryByAccountId", {}, account_id=ACCOUNT) + text = str(err.value) + for secret in ("access-token-555555", "developer-token-123456", "client-secret-abcdef", "refresh-token-987654"): + assert secret not in text + assert "CampaignServiceInvalidRequest" in text and "[redacted]" in text and creds.refreshes == 0 + + def test_a_lost_write_is_not_called_safe_to_retry(self, creds): + import requests + + with patch("requests.request", side_effect=requests.Timeout("read timed out")), \ + pytest.raises(MicrosoftAdsApiError) as err: + client.campaign_request(_config(), "AdExtensions", {}, account_id=ACCOUNT, mutation=True) + assert "may or may not have been made" in str(err.value) and "try again" not in str(err.value) + + @pytest.mark.parametrize("service,path", [ + ("customer", "Accounts/Search"), ("reporting", "GenerateReport/Submit"), + ("reporting", "GenerateReport/Poll"), ("campaign", "Campaigns/QueryByAccountId"), + ]) + def test_a_lost_read_says_try_again(self, creds, service, path): + # Delta finding 9: reads are reads, whatever their path is called. + import requests + + with patch("requests.request", side_effect=requests.Timeout("read timed out")), \ + pytest.raises(MicrosoftAdsApiError) as err: + client.ms_request(_config(), service, path, {}, account_id=ACCOUNT) + assert "try again" in str(err.value) and "may or may not" not in str(err.value) + + def test_item_errors_in_a_successful_answer_carry_no_credentials(self): + # Delta finding 1: HTTP 200 with PartialErrors / NestedPartialErrors. + cfg = AdLoopConfig(microsoft_ads=MicrosoftAdsConfig( + developer_token="developer-token-123456", client_id="app-id", customer_id=CUSTOMER, ad_account_id=ACCOUNT)) + creds = _Creds() + creds.access_token = "access-token-555555" + reply = {"AdExtensionIdentities": [{"Id": 5001}, None], + "NestedPartialErrors": [{"Index": 1, "BatchErrors": [ + {"Index": 0, "ErrorCode": "InvalidCallout", "Message": "echo access-token-555555"}]}], + "PartialErrors": [{"Index": 1, "Message": "echo developer-token-123456"}]} + with patch("adloop.microsoft_ads.client._credentials", return_value=creds), \ + patch("requests.request", return_value=_Resp(200, reply)): + payload = client.campaign_request(cfg, "AdExtensions", {}, account_id=ACCOUNT, mutation=True) + text = json.dumps(payload) + assert "access-token-555555" not in text and "developer-token-123456" not in text + assert payload["AdExtensionIdentities"][0] == {"Id": 5001} and "[redacted]" in text + from adloop.microsoft_ads import manage + from adloop.safety.outcomes import PartialApplyError + + with pytest.raises(PartialApplyError) as err: + manage._raise_partial(payload, "callouts") + assert "access-token-555555" not in str(err.value) and err.value.created == {"callouts": ["5001"]} + + # -- finding 6: every Microsoft time zone has its own "today" + @staticmethod + def _at(monkeypatch, utc_text): + from datetime import datetime as real, timezone as tz + + instant = real.fromisoformat(utc_text).replace(tzinfo=tz.utc) + + class Frozen(real): + @classmethod + def now(cls, tzinfo=None): + return instant.astimezone(tzinfo) if tzinfo else instant.replace(tzinfo=None) + + monkeypatch.setattr(read, "datetime", Frozen) + + @pytest.mark.parametrize("zone,utc,yesterday", [ + ("OsakaSapporoTokyo", "2026-11-03T16:30:00", "2026-11-03"), # Tokyo is already Nov 4 + ("CanberraMelbourneSydney", "2026-11-04T13:30:00", "2026-11-04"), # Sydney (UTC+11 in Nov) is Nov 5 00:30 + ("Newfoundland", "2026-11-04T03:00:00", "2026-11-02"), # UTC-3:30 is still Nov 3 + ("MountainTimeUSCanada", "2026-11-04T06:30:00", "2026-11-02"), # guide spelling + ("MountainTime_US_Canada", "2026-11-04T06:30:00", "2026-11-02"), # table spelling + ("InternationalDateLineWest", "2026-11-04T11:00:00", "2026-11-02"), + ]) + def test_default_window_ends_on_the_accounts_yesterday(self, monkeypatch, zone, utc, yesterday): + self._at(monkeypatch, utc) + start, end = read.report_window("", "", zone) + assert end.isoformat() == yesterday and (end - start).days == 29 + + def test_every_mapped_zone_exists(self): + from zoneinfo import ZoneInfo + + for name, iana in read._TIME_ZONES.items(): + ZoneInfo(iana) + assert {"OsakaSapporoTokyo", "CanberraMelbourneSydney", "PacificTimeUSCanadaTijuana"} <= set(read._TIME_ZONES) + + def test_an_unknown_zone_is_said_out_loud(self): + assert read.zone_note("PacificTimeUSCanadaTijuana") is None + assert "not in AdLoop's Microsoft time zone table" in read.zone_note("MarsStandardTime") + + # -- delta finding 8: every value of Microsoft's TimeZoneType enum + TIME_ZONE_TYPE = ['AbuDhabiMuscat', 'Adelaide', 'Alaska', 'AlmatyNovosibirsk', 'AmsterdamBerlinBernRomeStockholmVienna', 'Arizona', 'AstanaDhaka', 'AthensBuckarestIstanbul', 'AtlanticTimeCanada', 'AucklandWellington', 'Azores', 'Baghdad', 'BakuTbilisiYerevan', 'BangkokHanoiJakarta', 'BeijingChongqingHongKongUrumqi', 'BelgradeBratislavaBudapestLjubljanaPrague', 'BogotaLimaQuito', 'Brasilia', 'Brisbane', 'BrusselsCopenhagenMadridParis', 'Bucharest', 'BuenosAiresGeorgetown', 'Cairo', 'CanberraMelbourneSydney', 'CapeVerdeIsland', 'CaracasLaPaz', 'CasablancaMonrovia', 'CentralAmerica', 'CentralTimeUSCanada', 'ChennaiKolkataMumbaiNewDelhi', 'ChihuahuaLaPazMazatlan', 'Darwin', 'EasternTimeUSCanada', 'Ekaterinburg', 'FijiKamchatkaMarshallIsland', 'Greenland', 'GreenwichMeanTimeDublinEdinburghLisbonLondon', 'GuadalajaraMexicoCityMonterrey', 'GuamPortMoresby', 'HararePretoria', 'Hawaii', 'HelsinkiKyivRigaSofiaTallinnVilnius', 'Hobart', 'IndianaEast', 'InternationalDateLineWest', 'IrkutskUlaanBataar', 'IslamabadKarachiTashkent', 'Jerusalem', 'Kabul', 'Kathmandu', 'Krasnoyarsk', 'KualaLumpurSingapore', 'KuwaitRiyadh', 'SolomonIslandNewCaledonia', 'MidAtlantic', 'MidwayIslandAndSamoa', 'MoscowStPetersburgVolgograd', 'MountainTimeUSCanada', 'Nairobi', 'Newfoundland', 'Nukualofa', 'OsakaSapporoTokyo', 'PacificTimeUSCanadaTijuana', 'Perth', 'Rangoon', 'Santiago', 'SarajevoSkopjeWarsawZagreb', 'Saskatchewan', 'Seoul', 'SriJayawardenepura', 'Taipei', 'Tehran', 'Vladivostok', 'WestCentralAfrica', 'Yakutsk'] + + def test_every_api_time_zone_is_mapped(self): + assert len(self.TIME_ZONE_TYPE) == 75 + assert [v for v in self.TIME_ZONE_TYPE if v not in read._TIME_ZONES] == [] + + def test_karachi_accounts_get_their_own_yesterday(self, monkeypatch): + self._at(monkeypatch, "2026-11-03T20:30:00") # Karachi (UTC+5) is already Nov 4 + start, end = read.report_window("", "", "IslamabadKarachiTashkent") + assert end.isoformat() == "2026-11-03" + + +_SITE_AND_OFFLINE_GOALS = {"ConversionGoals": [ + {"Id": "31", "Name": "Quote form", "Type": "Event", "Status": "Active", "TagId": "400500600", + "TrackingStatus": "RecordingConversions", "ExcludeFromBidding": False}, + {"Id": "32", "Name": "Booked jobs", "Type": "OfflineConversion", "Status": "Active", + "TrackingStatus": "RecordingConversions", "ExcludeFromBidding": False}, +]} + + +class TestInStoreGoalPilot: + """Asking for InStoreTransaction goals fails for accounts outside Microsoft's in-store pilot.""" + + def _without_pilot(self, body): + if "InStoreTransaction" in body["ConversionGoalTypes"]: + raise MicrosoftAdsApiError( + "Microsoft Advertising API returned 400 for ConversionGoals/QueryByIds", + status=400, codes=["InStoreTransactionPilotNotEnabledForCustomer", "5359"], + ) + return _SITE_AND_OFFLINE_GOALS + + def test_setup_works_without_the_pilot(self): + calls, _, ctx = _fake_api({("campaign", "ConversionGoals/QueryByIds"): self._without_pilot}) + with ctx: + result = read.get_microsoft_conversion_setup(_config()) + by_check = {c["check"]: c for c in result["checks"]} + assert by_check["goal 'Quote form'"]["status"] == "pass" + assert by_check["goal 'Booked jobs'"]["status"] == "pass" + asked = [c[2]["ConversionGoalTypes"] for c in calls if c[1] == "ConversionGoals/QueryByIds"] + assert asked == [read.CONVERSION_GOAL_TYPES, + "Url, Duration, PagesViewedPerVisit, Event, AppInstall, OfflineConversion"] + + def test_pilot_accounts_keep_in_store_goals(self): + in_store = {"ConversionGoals": [ + {"Id": "33", "Name": "Store visits", "Type": "InStoreTransaction", "Status": "Active", + "TrackingStatus": "RecordingConversions", "ExcludeFromBidding": False}, + ]} + calls, _, ctx = _fake_api({("campaign", "ConversionGoals/QueryByIds"): in_store}) + with ctx: + result = read.get_microsoft_conversion_setup(_config()) + assert any(c["check"] == "goal 'Store visits'" for c in result["checks"]) + asked = [c[2]["ConversionGoalTypes"] for c in calls if c[1] == "ConversionGoals/QueryByIds"] + assert asked == [read.CONVERSION_GOAL_TYPES] and "InStoreTransaction" in asked[0] + + def test_other_goal_errors_are_not_retried(self): + refused = MicrosoftAdsApiError("Microsoft Advertising API returned 400", status=400, + codes=["CampaignServiceInvalidAccountId", "1100"]) + calls, _, ctx = _fake_api({("campaign", "ConversionGoals/QueryByIds"): refused}) + with ctx, pytest.raises(MicrosoftAdsApiError): + read.get_microsoft_conversion_setup(_config()) + assert len([c for c in calls if c[1] == "ConversionGoals/QueryByIds"]) == 1 + + def test_pilot_fault_from_the_api_is_matched_by_code(self, creds): + fault = {"Type": "ApiFaultDetail", "TrackingId": "trk-9", "BatchErrors": [], + "OperationErrors": [{"Code": 5359, "ErrorCode": "InStoreTransactionPilotNotEnabledForCustomer", + "Message": "In-Store Transaction pilot not enabled for current customer."}]} + with patch("requests.request", side_effect=[_Resp(400, fault), _Resp(200, _SITE_AND_OFFLINE_GOALS)]) as req: + goals = read._conversion_goals(_config(), ACCOUNT, CUSTOMER) + assert [g["Name"] for g in goals] == ["Quote form", "Booked jobs"] + sent = [c.kwargs["json"]["ConversionGoalTypes"] for c in req.call_args_list] + assert "InStoreTransaction" in sent[0] and "InStoreTransaction" not in sent[1] diff --git a/tests/test_microsoft_ads_manage.py b/tests/test_microsoft_ads_manage.py new file mode 100644 index 00000000..332d19c3 --- /dev/null +++ b/tests/test_microsoft_ads_manage.py @@ -0,0 +1,1632 @@ +"""Microsoft Advertising management against a stateful fake Campaign Management API. + +Every write goes through draft → preview → confirm_and_apply. The fake keeps +campaigns, criteria, ad groups, keywords, ads, negatives, shared lists and +extensions in memory and applies writes to them, so the tests check both the +exact REST bodies Microsoft receives and the state that results. +""" + +from __future__ import annotations + +import copy +import gzip +import json +from unittest.mock import patch + +import pytest + +from adloop.ads import write as ads_write +from adloop.config import AdLoopConfig, MicrosoftAdsConfig, SafetyConfig +from adloop.microsoft_ads import manage, read +from adloop.microsoft_ads.auth import MicrosoftAdsApiError +from adloop.safety import preview as preview_store +from adloop.safety.preview import InMemoryPlanStore + +ACCOUNT = "100200300" +CUSTOMER = "900800700" +CAMPAIGN = "500100200" + + +def _text(value) -> str: + return json.dumps(value, ensure_ascii=False, default=str) + + +class FakeMicrosoft: + def __init__(self): + self.account = {"Id": int(ACCOUNT), "Name": "Acme Plumbing", "CurrencyCode": "USD", + "TimeZone": "PacificTimeUSCanadaTijuana", "AccountLifeCycleStatus": "Active", + "ParentCustomerId": int(CUSTOMER)} + self.campaigns = { + CAMPAIGN: {"Id": int(CAMPAIGN), "Name": "Acme Plumbing - Search", "Status": "Active", "DailyBudget": 35.0, + "BudgetType": "DailyBudgetStandard", "BudgetId": None, "CampaignType": "Search", + "BiddingScheme": {"Type": "EnhancedCpc"}, "TrackingUrlTemplate": None, "FinalUrlSuffix": None}, + "600": {"Id": 600, "Name": "Brand", "Status": "Active", "DailyBudget": 10.0, "BudgetId": None, + "BiddingScheme": {"Type": "MaxConversions", "MaxCpc": {"Amount": 12.0}}}, + } + self.criteria = { + CAMPAIGN: [ + {"Id": 1001, "Type": "BiddableCampaignCriterion", "CampaignId": int(CAMPAIGN), + "Criterion": {"Type": "Location", "LocationId": 190, "DisplayName": "Springfield, Illinois"}}, + {"Id": 1002, "Type": "NegativeCampaignCriterion", "CampaignId": int(CAMPAIGN), + "Criterion": {"Type": "Location", "LocationId": 191, "DisplayName": "Los Angeles, California"}}, + {"Id": 1003, "Type": "BiddableCampaignCriterion", "CampaignId": int(CAMPAIGN), + "Criterion": {"Type": "LocationIntent", "IntentOption": "PeopleInOrSearchingForOrViewingPages"}}, + ], + "600": [], + } + self.ad_groups = { + "11": {"Id": 11, "Name": "Drains", "Status": "Active", "CpcBid": {"Amount": 8.0}, + "Network": "OwnedAndOperatedAndSyndicatedSearch", "AudienceAdsBidAdjustment": None, "_campaign": CAMPAIGN}, + "12": {"Id": 12, "Name": "Water heaters", "Status": "Paused", "CpcBid": {"Amount": 6.0}, + "Network": "OwnedAndOperatedOnly", "_campaign": CAMPAIGN}, + "21": {"Id": 21, "Name": "Brand terms", "Status": "Active", "CpcBid": {"Amount": 3.0}, "_campaign": "600"}, + } + self.keywords = { + "101": {"Id": 101, "Text": "drain cleaning", "MatchType": "Phrase", "Bid": {"Amount": None}, "Status": "Active", "_group": "11"}, + "102": {"Id": 102, "Text": "plumber", "MatchType": "Broad", "Bid": {"Amount": 9.0}, "Status": "Active", "_group": "11"}, + "103": {"Id": 103, "Text": "water heater", "MatchType": "Exact", "Bid": {"Amount": None}, "Status": "Active", "_group": "12"}, + "201": {"Id": 201, "Text": "acme plumbing", "MatchType": "Exact", "Bid": {"Amount": None}, "Status": "Active", "_group": "21"}, + } + self.ads = { + "301": {"Id": 301, "Type": "ResponsiveSearch", "Status": "Active", "_group": "11", + "Headlines": [{"Asset": {"Type": "TextAsset", "Text": t}} for t in ("Drain Cleaning", "Same Day", "Call Now")], + "Descriptions": [{"Asset": {"Type": "TextAsset", "Text": d}} for d in ("Licensed.", "Local.")], + "FinalUrls": ["https://example.com/drain"], "Path1": "drain", "Path2": None}, + } + self.negatives = {("Campaign", CAMPAIGN): [{"Id": 501, "Text": "free", "MatchType": "Phrase"}]} + self.lists = {"900": {"Id": 900, "Name": "Junk", "Type": "NegativeKeywordList", "ItemCount": 2}} + self.items = {"900": [{"Id": 9001, "Type": "NegativeKeyword", "Text": "jobs", "MatchType": "Phrase"}, + {"Id": 9002, "Type": "NegativeKeyword", "Text": "diy", "MatchType": "Phrase"}]} + self.associations = [{"SharedEntityId": 900, "EntityId": int(CAMPAIGN)}] + self.extensions = { + "7001": {"Id": 7001, "Type": "SitelinkAdExtension", "DisplayText": "Drain Cleaning", + "FinalUrls": ["https://example.com/drain"]}, + "7002": {"Id": 7002, "Type": "CalloutAdExtension", "Text": "Licensed"}, + } + self.ext_links = [("7001", CAMPAIGN, "Campaign"), ("7002", CAMPAIGN, "Campaign")] + self.media: dict[str, dict] = {} + self.goals = [{"Id": 9, "Name": "Lead", "Type": "Event", "Status": "Active", "ExcludeFromBidding": False}] + # Accounts outside Microsoft's in-store pilot cannot ask for InStoreTransaction goals. + self.in_store_pilot = True + self.calls: list[dict] = [] + self.fail: dict[tuple, Exception] = {} + self._next = 5000 + + def _id(self) -> int: + self._next += 1 + return self._next + + def writes(self) -> list[dict]: + return [c for c in self.calls if c["method"] in ("PUT", "DELETE") or c["path"] in self._write_paths] + + _write_paths = {"Campaigns", "CampaignCriterions", "AdGroups", "Keywords", "Ads", "EntityNegativeKeywords", + "SharedEntity", "ListItems", "SharedEntityAssociations/Set", "SharedEntityAssociations", + "AdExtensions", "AdExtensionsAssociations/Set", "AdExtensionsAssociations", "Media"} + + @staticmethod + def _pub(obj: dict) -> dict: + return {k: copy.deepcopy(v) for k, v in obj.items() if not k.startswith("_")} + + def _listed_extension(self, ext_id: str) -> dict: + """An extension as the association query returns it: image extensions come + without ImageMediaIds, Images, DisplayText and Layouts (checked live).""" + ext = copy.deepcopy(self.extensions[ext_id]) + if ext.get("Type") == "ImageAdExtension": + for field in ("Images", "DisplayText", "Layouts"): + ext.pop(field, None) + ext["ImageMediaIds"] = None + return ext + + def __call__(self, config, service, path, body=None, *, method="POST", account_id="", customer_id="", mutation=False): + body = copy.deepcopy(body or {}) + self.calls.append({"service": service, "path": path, "method": method, "body": body}) + if (method, path) in self.fail: + raise self.fail[(method, path)] + if service == "customer" and path == "Account/Query": + return {"Account": dict(self.account)} + # -------- reads + if path == "Campaigns/QueryByAccountId": + # Like Microsoft: optional fields come back only when requested. + asked = {x.strip() for x in str(body.get("ReturnAdditionalFields") or "").split(",")} + out = [] + for c in self.campaigns.values(): + c = self._pub(c) + if "TargetCpaInMaxConversion" not in asked and isinstance(c.get("BiddingScheme"), dict): + c["BiddingScheme"].pop("TargetCpa", None) + if "AdScheduleUseSearcherTimeZone" not in asked: + c.pop("AdScheduleUseSearcherTimeZone", None) + out.append(c) + return {"Campaigns": out} + if path == "CampaignCriterions/QueryByIds": + kind = body["CriterionType"] + wanted = {"Location": "Location", "LocationIntent": "LocationIntent", "DayTime": "DayTime", "Radius": "Radius"}[kind] + return {"CampaignCriterions": [copy.deepcopy(c) for c in self.criteria.get(str(body["CampaignId"]), []) + if c["Criterion"]["Type"].replace("Criterion", "") == wanted]} + if path == "AdGroups/QueryByCampaignId": + return {"AdGroups": [self._pub(g) for g in self.ad_groups.values() if g["_campaign"] == str(body["CampaignId"])]} + if path == "Keywords/QueryByAdGroupId": + return {"Keywords": [self._pub(k) for k in self.keywords.values() if k["_group"] == str(body["AdGroupId"])]} + if path == "Ads/QueryByAdGroupId": + return {"Ads": [self._pub(a) for a in self.ads.values() if a["_group"] == str(body["AdGroupId"])]} + if path == "ConversionGoals/QueryByIds": + if not self.in_store_pilot and "InStoreTransaction" in body["ConversionGoalTypes"]: + raise MicrosoftAdsApiError( + "InStoreTransactionPilotNotEnabledForCustomer: In-Store Transaction pilot not enabled", + status=400, codes=["InStoreTransactionPilotNotEnabledForCustomer", "5359"]) + return {"ConversionGoals": copy.deepcopy(self.goals)} + if path == "NegativeKeywords/QueryByEntityIds": + key = (body["EntityType"], str(body["EntityIds"][0])) + return {"EntityNegativeKeywords": [{"EntityId": body["EntityIds"][0], "EntityType": key[0], + "NegativeKeywords": copy.deepcopy(self.negatives.get(key, []))}]} + if path == "SharedEntities/Query": + return {"SharedEntities": copy.deepcopy(list(self.lists.values()))} + if path == "ListItems/QueryBySharedList": + return {"ListItems": copy.deepcopy(self.items.get(str(body["SharedList"]["Id"]), []))} + if path == "SharedEntityAssociations/QueryByEntityIds": + ids = {int(i) for i in body["EntityIds"]} + return {"Associations": [dict(a, EntityType="Campaign", SharedEntityType="NegativeKeywordList") + for a in self.associations if a["EntityId"] in ids]} + if path == "AdExtensionsAssociations/Query": + # One collection per requested entity, at most 100 entities, like Microsoft. + assert len(body["EntityIds"]) <= 100 + wanted = {x.strip() for x in body["AdExtensionType"].split(",")} + collections = [] + for entity in body["EntityIds"]: + links = [l for l in self.ext_links if l[1] == str(entity) and l[2] == body["AssociationType"] + and self.extensions[l[0]]["Type"] in wanted] + collections.append({"AdExtensionAssociations": [ + {"AdExtension": self._listed_extension(e), "AssociationType": a, "EntityId": int(o), + "EditorialStatus": "Active"} for e, o, a in links]} if links else None) + return {"AdExtensionAssociationCollection": collections} + if path == "AdExtensions/QueryByIds": + # Like Microsoft: Images, DisplayText and Layouts only when asked for, + # and an unknown additional field fails the whole request. + extra = {x.strip() for x in (body.get("ReturnAdditionalFields") or "").split(",") if x.strip()} + if extra - {"Images", "DisplayText", "Layouts", "LogoImages"}: + raise MicrosoftAdsApiError("NullRequest: The request message is null.", status=400) + out = [] + for i in body["AdExtensionIds"]: + ext = self.extensions.get(str(i)) + if ext is None: + out.append(None) + continue + shown = self._listed_extension(str(i)) + if "Images" in extra and ext["Type"] == "ImageAdExtension": + shown["Images"] = [{"Asset": {"Type": "ImageAsset", "Id": str(m), "SubType": "LandscapeImageMedia"}} + for m in ext.get("ImageMediaIds") or []] + for field in ("DisplayText", "Layouts"): + if field in extra and field in ext: + shown[field] = ext[field] + out.append(shown) + return {"AdExtensions": out, "PartialErrors": []} + if path == "MediaMetaData/QueryByIds": + width, height = 1200, 628 + return {"MediaMetaData": [ + {"Id": str(m), "Type": "Image", "MediaType": "GenericImage", "Representations": [ + {"Type": "ImageMediaRepresentation", "Name": "Original", "Width": width, "Height": height, + "Url": f"https://www.bing.com/th?id=OADD2.{m}"}]} for m in body["MediaIds"]]} + if path == "GeoLocationsFileUrl/Query": + return {"FileUrl": "https://geo.example/locations.csv.gz?sig=SECRET", "LastModifiedTimeUtc": "2026-10-01T00:00:00"} + # -------- writes + if path == "Campaigns": + if method == "POST": + ids = [] + for c in body["Campaigns"]: + cid = self._id() + self.campaigns[str(cid)] = {"Id": cid, **c} + self.criteria[str(cid)] = [] + ids.append(cid) + return {"CampaignIds": ids, "PartialErrors": []} + if method == "PUT": + for c in body["Campaigns"]: + self.campaigns[str(c["Id"])].update({k: v for k, v in c.items() if k != "Id"}) + return {"PartialErrors": []} + for cid in body["CampaignIds"]: + self.campaigns.pop(str(cid)) + return {"PartialErrors": []} + if path == "CampaignCriterions": + if method == "POST": + # Microsoft refuses overlapping DayTime windows in a campaign, + # and more than seven on one day. + for c in body["CampaignCriterions"]: + if c["Criterion"]["Type"] == "DayTimeCriterion": + day = c["Criterion"]["Day"] + on_day = sum(1 for e in self.criteria.get(str(c["CampaignId"]), []) + if e["Criterion"]["Type"] == "DayTime" and e["Criterion"]["Day"] == day) + if on_day >= 7: + raise MicrosoftAdsApiError("CampaignCriterionDayTimeLimit: at most seven per day", + status=400, codes=["CampaignCriterionDayTimeLimit"]) + self.criteria.setdefault(str(c["CampaignId"]), []).append( + {"Id": -1, "Criterion": {"Type": "DayTime", "Day": day}}) # counted, removed below + self.criteria[str(body["CampaignCriterions"][0]["CampaignId"])] = [ + e for e in self.criteria.get(str(body["CampaignCriterions"][0]["CampaignId"]), []) if e["Id"] != -1] + for c in body["CampaignCriterions"]: + if c["Criterion"]["Type"] == "DayTimeCriterion": + span = manage._block_span(c["Criterion"]) + for e in self.criteria.get(str(c["CampaignId"]), []): + if e["Criterion"]["Type"] == "DayTime": + other = manage._block_span(e["Criterion"]) + if other[0] == span[0] and span[1] < other[2] and other[1] < span[2]: + raise MicrosoftAdsApiError("CampaignCriterionDayTimeOverlap: day and time ranges overlap", + status=400, codes=["CampaignCriterionDayTimeOverlap"]) + ids = [] + for c in body["CampaignCriterions"]: + crit = copy.deepcopy(c) + crit["Id"] = self._id() + crit["Criterion"]["Type"] = crit["Criterion"]["Type"].replace("Criterion", "") + self.criteria.setdefault(str(c["CampaignId"]), []).append(crit) + ids.append(crit["Id"]) + return {"CampaignCriterionIds": ids, "PartialErrors": []} + if method == "PUT": + for c in body["CampaignCriterions"]: + for existing in self.criteria[str(c["CampaignId"])]: + if str(existing["Id"]) == str(c["Id"]): + existing["Criterion"].update({k: v for k, v in c["Criterion"].items() if k != "Type"}) + return {"PartialErrors": []} + drop = {int(i) for i in body["CampaignCriterionIds"]} + self.criteria[str(body["CampaignId"])] = [c for c in self.criteria[str(body["CampaignId"])] if c["Id"] not in drop] + return {"PartialErrors": []} + if path == "AdGroups": + if method == "POST": + ids = [] + for g in body["AdGroups"]: + gid = self._id() + self.ad_groups[str(gid)] = {"Id": gid, **g, "_campaign": str(body["CampaignId"])} + ids.append(gid) + return {"AdGroupIds": ids, "PartialErrors": []} + if method == "PUT": + for g in body["AdGroups"]: + self.ad_groups[str(g["Id"])].update({k: v for k, v in g.items() if k != "Id"}) + return {"PartialErrors": []} + for gid in body["AdGroupIds"]: + self.ad_groups.pop(str(gid)) + return {"PartialErrors": []} + if path == "Keywords": + if method == "POST": + ids = [] + for k in body["Keywords"]: + kid = self._id() + self.keywords[str(kid)] = {"Id": kid, **k, "_group": str(body["AdGroupId"])} + ids.append(kid) + return {"KeywordIds": ids, "PartialErrors": []} + if method == "PUT": + for k in body["Keywords"]: + self.keywords[str(k["Id"])].update({x: v for x, v in k.items() if x != "Id"}) + return {"PartialErrors": []} + for kid in body["KeywordIds"]: + self.keywords.pop(str(kid)) + return {"PartialErrors": []} + if path == "Ads": + if method == "POST": + ids = [] + for a in body["Ads"]: + aid = self._id() + self.ads[str(aid)] = {"Id": aid, **a, "_group": str(body["AdGroupId"])} + ids.append(aid) + return {"AdIds": ids, "PartialErrors": []} + if method == "PUT": + for a in body["Ads"]: + self.ads[str(a["Id"])].update({k: v for k, v in a.items() if k != "Id"}) + return {"PartialErrors": []} + for aid in body["AdIds"]: + self.ads.pop(str(aid)) + return {"PartialErrors": []} + if path == "EntityNegativeKeywords": + entry = body["EntityNegativeKeywords"][0] + key = (entry["EntityType"], str(entry["EntityId"])) + if method == "POST": + for n in entry["NegativeKeywords"]: + self.negatives.setdefault(key, []).append({"Id": self._id(), **n}) + return {"NegativeKeywordIds": [{"Ids": []}], "NestedPartialErrors": []} + drop = {n["Id"] for n in entry["NegativeKeywords"]} + self.negatives[key] = [n for n in self.negatives.get(key, []) if n["Id"] not in drop] + return {"NestedPartialErrors": []} + if path == "SharedEntity": + lid = self._id() + self.lists[str(lid)] = {"Id": lid, **body["SharedEntity"], "ItemCount": len(body["ListItems"])} + self.items[str(lid)] = [{"Id": self._id(), **i} for i in body["ListItems"]] + return {"SharedEntityId": lid, "ListItemIds": [], "PartialErrors": []} + if path == "ListItems": + lid = str(body["SharedList"]["Id"]) + if method == "POST": + self.items[lid] += [{"Id": self._id(), **i} for i in body["ListItems"]] + return {"ListItemIds": [], "PartialErrors": []} + drop = {int(i) for i in body["ListItemIds"]} + self.items[lid] = [i for i in self.items[lid] if i["Id"] not in drop] + return {"PartialErrors": []} + if path == "SharedEntityAssociations/Set": + for a in body["Associations"]: + self.associations.append({"SharedEntityId": a["SharedEntityId"], "EntityId": a["EntityId"]}) + return {"PartialErrors": []} + if path == "SharedEntityAssociations" and method == "DELETE": + drop = {(a["SharedEntityId"], a["EntityId"]) for a in body["Associations"]} + self.associations = [a for a in self.associations if (a["SharedEntityId"], a["EntityId"]) not in drop] + return {"PartialErrors": []} + if path == "Media" and method == "POST": + assert len(body["Media"]) <= 10 + ids = [] + for m in body["Media"]: + mid = self._id() + self.media[str(mid)] = m + ids.append(mid) + return {"MediaIds": ids} + if path == "AdExtensions": + identities = [] + for e in body["AdExtensions"]: + eid = self._id() + self.extensions[str(eid)] = {"Id": eid, **e} + identities.append({"Id": eid, "Version": 1}) + return {"AdExtensionIdentities": identities, "NestedPartialErrors": []} + if path == "AdExtensionsAssociations/Set": + for a in body["AdExtensionIdToEntityIdAssociations"]: + self.ext_links.append((str(a["AdExtensionId"]), str(a["EntityId"]), body["AssociationType"])) + return {"PartialErrors": []} + if path == "AdExtensionsAssociations" and method == "DELETE": + drop = {(str(a["AdExtensionId"]), str(a["EntityId"]), body["AssociationType"]) + for a in body["AdExtensionIdToEntityIdAssociations"]} + self.ext_links = [l for l in self.ext_links if l not in drop] + return {"PartialErrors": []} + raise AssertionError(f"unexpected Microsoft call {method} {service} {path}") + + +@pytest.fixture +def api(): + fake = FakeMicrosoft() + with patch("adloop.microsoft_ads.client.ms_request", side_effect=fake): + yield fake + + +@pytest.fixture(autouse=True) +def _fresh(monkeypatch): + preview_store.set_plan_store(InMemoryPlanStore()) + read.reset_account_cache() + read._GEO_CACHE.clear() + monkeypatch.setattr("adloop.ads.write._validate_urls", lambda urls, timeout=10: ({u: None for u in urls}, {})) + yield + preview_store.set_plan_store(InMemoryPlanStore()) + + +@pytest.fixture +def config(tmp_path): + return AdLoopConfig( + microsoft_ads=MicrosoftAdsConfig(developer_token="dt", client_id="app", customer_id=CUSTOMER, ad_account_id=ACCOUNT), + safety=SafetyConfig(max_daily_budget=100.0, max_bid_increase_pct=100, require_dry_run=False, + log_file=str(tmp_path / "audit.log")), + ) + + +def _apply(config, preview): + assert "plan_id" in preview, preview + dry = ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=True) + assert dry["status"] == "DRY_RUN_SUCCESS", dry + result = ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=False) + assert result["status"] == "APPLIED", result + return result["result"] + + +def _last(api, path, method=None): + return [c for c in api.calls if c["path"] == path and (method is None or c["method"] == method)][-1] + + +# --------------------------------------------------------------------------- +# Campaign settings +# --------------------------------------------------------------------------- + + +class TestCampaignSettings: + def test_move_to_max_conversions_with_a_target(self, api, config): + preview = manage.update_microsoft_campaign(config, campaign_id="600", bidding_strategy="MaxConversions", target_cpa=40) + assert preview["platform"] == "microsoft" and preview["operation"] == "microsoft_update_campaign" + result = _apply(config, preview) + body = _last(api, "Campaigns", "PUT")["body"] + assert body == {"AccountId": ACCOUNT, "Campaigns": [{"Id": "600", "BiddingScheme": { + "Type": "MaxConversions", "TargetCpa": 40.0, "MaxCpc": {"Amount": 12.0}}}]} + assert result["updated"] == ["BiddingScheme"] + assert api.campaigns["600"]["BiddingScheme"]["TargetCpa"] == 40.0 + + def test_strategy_change_warns_and_targetcpa_maps(self, api, config): + preview = manage.update_microsoft_campaign(config, campaign_id="600", bidding_strategy="TargetCpa", target_cpa=30) + assert preview["changes"]["update"]["BiddingScheme"]["Type"] == "MaxConversions" + switched = manage.update_microsoft_campaign(config, campaign_id="600", bidding_strategy="MaxClicks") + assert any("learning period" in w for w in switched["warnings"]) + + def test_manual_bidding_refused_with_broad_keywords(self, api, config): + result = manage.update_microsoft_campaign(config, campaign_id=CAMPAIGN, bidding_strategy="ManualCpc") + assert "broad-match" in _text(result) + + def test_max_cpc_cannot_be_added(self, api, config): + api.campaigns["600"]["BiddingScheme"] = {"Type": "MaxConversions"} + assert "no longer lets a campaign add a maximum CPC" in _text( + manage.update_microsoft_campaign(config, campaign_id="600", max_cpc=5)) + + def test_max_conversions_without_goals_warns(self, api, config): + api.goals = [] + preview = manage.update_microsoft_campaign(config, campaign_id="600", target_cpa=25) + assert any("nothing to optimize" in w for w in preview["warnings"]) + + def test_tracking_template_rules(self, api, config): + assert "must start with" in _text(manage.update_microsoft_campaign(config, campaign_id=CAMPAIGN, tracking_url_template="track.me")) + preview = manage.update_microsoft_campaign(config, campaign_id=CAMPAIGN, tracking_url_template="{lpurl}?src=bing", + final_url_suffix="utm_source=bing&utm_medium=cpc") + assert preview["changes"]["update"] == {"Id": CAMPAIGN, "TrackingUrlTemplate": "{lpurl}?src=bing", + "FinalUrlSuffix": "utm_source=bing&utm_medium=cpc"} + api.campaigns[CAMPAIGN]["FinalUrlSuffix"] = "utm_source=bing" + removal = manage.update_microsoft_campaign(config, campaign_id=CAMPAIGN, final_url_suffix="") + assert removal["changes"]["update"]["FinalUrlSuffix"] == "" and any("removed" in w for w in removal["warnings"]) + + def test_name_rules_and_nothing_to_change(self, api, config): + assert "already named" in _text(manage.update_microsoft_campaign(config, campaign_id=CAMPAIGN, name="Brand")) + assert "Nothing to change" in manage.update_microsoft_campaign(config, campaign_id=CAMPAIGN, name="Acme Plumbing - Search")["error"] + assert "was not found" in manage.update_microsoft_campaign(config, campaign_id="999", name="X")["error"] + + def test_edit_in_microsoft_after_the_draft_blocks_the_apply(self, api, config): + preview = manage.update_microsoft_campaign(config, campaign_id="600", target_cpa=40) + api.campaigns["600"]["BiddingScheme"] = {"Type": "MaxClicks"} + result = ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=False) + assert "BiddingScheme changed since the draft" in result["error"] + assert not [c for c in api.calls if c["method"] == "PUT"] + + +# --------------------------------------------------------------------------- +# Targeting +# --------------------------------------------------------------------------- + + +class TestTargeting: + def test_location_replace_adds_before_it_removes(self, api, config): + preview = manage.update_microsoft_campaign_targeting(config, campaign_id=CAMPAIGN, location_ids=["200", "201"], + excluded_location_ids=[]) + shown = preview["changes"]["changes"] + assert shown["locations"]["removed"] == ["Springfield, Illinois"] + assert shown["excluded_locations"]["to"] == [] + _apply(config, preview) + writes = [c for c in api.calls if c["path"] == "CampaignCriterions"] + assert [c["method"] for c in writes] == ["POST", "DELETE"] + assert writes[0]["body"]["CriterionType"] == "Targets" + assert writes[0]["body"]["CampaignCriterions"][0] == { + "Type": "BiddableCampaignCriterion", "CampaignId": CAMPAIGN, + "Criterion": {"Type": "LocationCriterion", "LocationId": 200}, + "CriterionBid": {"Type": "BidMultiplier", "Multiplier": 0}} + assert sorted(writes[1]["body"]["CampaignCriterionIds"]) == [1001, 1002] + locations = {c["Criterion"].get("LocationId") for c in api.criteria[CAMPAIGN] if c["Criterion"]["Type"] == "Location"} + assert locations == {200, 201} + + def test_location_guards(self, api, config): + assert "serve everywhere" in _text(manage.update_microsoft_campaign_targeting(config, campaign_id=CAMPAIGN, location_ids=[])) + assert "both included and excluded" in _text(manage.update_microsoft_campaign_targeting( + config, campaign_id=CAMPAIGN, location_ids=["5"], excluded_location_ids=["5"])) + assert "are numbers" in _text(manage.update_microsoft_campaign_targeting(config, campaign_id=CAMPAIGN, location_ids=["Springfield"])) + assert "Nothing to change" in manage.update_microsoft_campaign_targeting(config, campaign_id=CAMPAIGN)["error"] + assert "already matches" in manage.update_microsoft_campaign_targeting(config, campaign_id=CAMPAIGN, location_ids=["190"])["error"] + + def test_intent_updates_the_existing_criterion(self, api, config): + preview = manage.update_microsoft_campaign_targeting(config, campaign_id=CAMPAIGN, location_intent="PeopleIn") + _apply(config, preview) + put = _last(api, "CampaignCriterions", "PUT")["body"]["CampaignCriterions"][0] + assert put["Id"] == "1003" and put["Criterion"] == {"Type": "LocationIntentCriterion", "IntentOption": "PeopleIn"} + assert "CriterionBid" not in put + + def test_intent_is_added_when_missing(self, api, config): + preview = manage.update_microsoft_campaign_targeting(config, campaign_id="600", location_intent="PeopleIn") + assert preview["changes"]["operations"]["add"][0]["Criterion"]["Type"] == "LocationIntentCriterion" + wide = manage.update_microsoft_campaign_targeting(config, campaign_id="600", location_intent="PeopleInOrSearchingForOrViewingPages") + assert any("outside the locations" in w for w in wide["warnings"]) + + def test_first_schedule_is_double_confirmed(self, api, config): + schedule = [{"day_of_week": day, "start_hour": 6, "end_hour": 16, "end_minute": 30} + for day in ("Monday", "Tuesday", "Wednesday", "Thursday", "Friday")] + preview = manage.update_microsoft_campaign_targeting(config, campaign_id=CAMPAIGN, ad_schedule=schedule) + assert preview["requires_double_confirm"] is True + assert preview["changes"]["changes"]["ad_schedule"]["to"][0] == "Mon 06:00–16:30" + assert any("PacificTimeUSCanadaTijuana" in w for w in preview["warnings"]) + _apply(config, preview) + sent = _last(api, "CampaignCriterions", "POST")["body"]["CampaignCriterions"] + assert sent[0]["Criterion"] == {"Type": "DayTimeCriterion", "Day": "Monday", "FromHour": 6, "FromMinute": "Zero", + "ToHour": 16, "ToMinute": "Thirty"} + # Replacing the schedule deletes the old windows; [] clears it. + cleared = manage.update_microsoft_campaign_targeting(config, campaign_id=CAMPAIGN, ad_schedule=[]) + assert cleared["requires_double_confirm"] is False + ops = cleared["changes"]["operations"] + assert len(ops["schedule_delete"]) == 5 and ops["schedule_add_first"] == ops["schedule_add_after"] == [] + + def test_schedule_validation(self, api, config): + bad = manage.update_microsoft_campaign_targeting(config, campaign_id=CAMPAIGN, ad_schedule=[ + {"day_of_week": "Monday", "start_hour": 8, "end_hour": 12}, + {"day_of_week": "Monday", "start_hour": 11, "end_hour": 14}, + {"day_of_week": "Funday", "start_hour": 1, "end_hour": 2}, + {"day_of_week": "Tuesday", "start_hour": 8, "end_hour": 9, "start_minute": 10}, + {"day_of_week": "Wednesday", "start_hour": 9, "end_hour": 8}, + {"day_of_week": "Thursday", "start_hour": 9, "end_hour": 24, "end_minute": 15}, + ]) + text = _text(bad) + for fragment in ("overlap", "Funday", "minutes are 0, 15, 30 or 45", "must end after it starts", "24 only with minute 0"): + assert fragment in text + + def test_targeting_changed_after_the_draft(self, api, config): + preview = manage.update_microsoft_campaign_targeting(config, campaign_id=CAMPAIGN, location_intent="PeopleIn") + api.criteria[CAMPAIGN].append({"Id": 1010, "Type": "BiddableCampaignCriterion", "CampaignId": int(CAMPAIGN), + "Criterion": {"Type": "Location", "LocationId": 300, "DisplayName": "Davis"}}) + dry = ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=True) + assert dry["status"] == "DRY_RUN_FAILED" and "targeting changed" in dry["error"] + + +# --------------------------------------------------------------------------- +# New campaign +# --------------------------------------------------------------------------- + + +class TestNewCampaign: + def test_created_paused_then_targeted(self, api, config): + preview = manage.draft_microsoft_campaign(config, name="Springfield Water Heaters", daily_budget=40, target_cpa=60, + languages=["English"], location_ids=["190"], excluded_location_ids=["191"]) + changes = preview["changes"] + assert changes["status_on_create"] == "Paused" and changes["monthly_maximum"] == 1216.0 + assert any("5× the target CPA" in w for w in preview["warnings"]) + result = _apply(config, preview) + campaign = _last(api, "Campaigns", "POST")["body"]["Campaigns"][0] + assert campaign == {"Name": "Springfield Water Heaters", "BudgetType": "DailyBudgetStandard", "DailyBudget": 40.0, + "CampaignType": "Search", "Languages": ["English"], "Status": "Paused", + "TimeZone": "PacificTimeUSCanadaTijuana", + "BiddingScheme": {"Type": "MaxConversions", "TargetCpa": 60.0}} + criteria = _last(api, "CampaignCriterions", "POST")["body"]["CampaignCriterions"] + assert {c["CampaignId"] for c in criteria} == {result["campaign_id"]} + assert [c["Type"] for c in criteria] == ["BiddableCampaignCriterion", "NegativeCampaignCriterion", "BiddableCampaignCriterion"] + assert criteria[2]["Criterion"] == {"Type": "LocationIntentCriterion", "IntentOption": "PeopleIn"} + + def test_guards(self, api, config): + no_lang = manage.draft_microsoft_campaign(config, name="X", daily_budget=10, location_ids=["190"]) + assert "languages is required" in _text(no_lang) + no_geo = manage.draft_microsoft_campaign(config, name="X", daily_budget=10, languages=["English"]) + assert "location_ids is required" in _text(no_geo) + assert "exceeds maximum" in manage.draft_microsoft_campaign(config, name="X", daily_budget=500, languages=["English"], location_ids=["190"])["error"] + assert "already exists" in _text(manage.draft_microsoft_campaign(config, name="brand", daily_budget=10, languages=["English"], location_ids=["190"])) + api.goals = [] + warn = manage.draft_microsoft_campaign(config, name="New", daily_budget=10, languages=["English"], location_ids=["190"]) + assert any("nothing to optimize" in w for w in warn["warnings"]) + + def test_failed_targeting_step_names_the_created_campaign_and_retry_is_refused(self, api, config): + preview = manage.draft_microsoft_campaign(config, name="Half done", daily_budget=10, languages=["English"], location_ids=["190"]) + api.fail[("POST", "CampaignCriterions")] = MicrosoftAdsApiError("Microsoft refused: InvalidLocationId", status=400) + result = ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=False) + assert result["status"] == "PARTIAL_APPLY" + assert "created campaign" in result["error"] and "(paused)" in result["error"] and "InvalidLocationId" in result["error"] + del api.fail[("POST", "CampaignCriterions")] + # The plan is retired: it cannot be replayed into a second campaign. + retry = ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=False) + assert "No pending plan" in retry["error"] + assert sum(1 for c in api.campaigns.values() if c["Name"] == "Half done") == 1 + # A fresh draft of the same campaign is refused by name. + assert "already exists" in _text(manage.draft_microsoft_campaign( + config, name="Half done", daily_budget=10, languages=["English"], location_ids=["190"])) + + +# --------------------------------------------------------------------------- +# Ad groups and keywords +# --------------------------------------------------------------------------- + + +class TestAdGroupsAndKeywords: + def test_ad_group_with_keywords(self, api, config): + preview = manage.draft_microsoft_ad_group(config, campaign_id=CAMPAIGN, name="Sewer", cpc_bid=7.5, + keywords=["sewer repair", {"text": "sewer line", "match_type": "exact", "bid": 9}]) + result = _apply(config, preview) + group = _last(api, "AdGroups", "POST")["body"] + assert group == {"CampaignId": CAMPAIGN, "AdGroups": [{"Name": "Sewer", "Network": "OwnedAndOperatedOnly", + "Status": "Active", "CpcBid": {"Amount": 7.5}}]} + keywords = _last(api, "Keywords", "POST")["body"] + assert keywords["AdGroupId"] == result["ad_group_id"] + assert keywords["Keywords"] == [{"Text": "sewer repair", "MatchType": "Phrase", "Status": "Active"}, + {"Text": "sewer line", "MatchType": "Exact", "Status": "Active", "Bid": {"Amount": 9.0}}] + + def test_ad_group_guards(self, api, config): + assert "needs cpc_bid" in _text(manage.draft_microsoft_ad_group(config, campaign_id=CAMPAIGN, name="No bid")) + assert "Broad match" in _text(manage.draft_microsoft_ad_group(config, campaign_id=CAMPAIGN, name="B", cpc_bid=5, + keywords=[{"text": "plumbing", "match_type": "Broad"}])) + assert "already has an ad group" in _text(manage.draft_microsoft_ad_group(config, campaign_id=CAMPAIGN, name="drains", cpc_bid=5)) + ok = manage.draft_microsoft_ad_group(config, campaign_id="600", name="Auto", keywords=[{"text": "acme", "match_type": "Broad"}]) + assert "plan_id" in ok # automated bidding allows broad and needs no bid + partners = manage.draft_microsoft_ad_group(config, campaign_id="600", name="Partners", network="OwnedAndOperatedAndSyndicatedSearch") + assert any("Syndicated" in w for w in partners["warnings"]) + + def test_ad_group_update(self, api, config): + preview = manage.update_microsoft_ad_group(config, ad_group_id="11", cpc_bid=10, network="OwnedAndOperatedOnly", + audience_ads_bid_adjustment=-100) + assert preview["changes"]["changes"]["audience_network"]["meaning"] == "off" + _apply(config, preview) + body = _last(api, "AdGroups", "PUT")["body"] + assert body == {"CampaignId": CAMPAIGN, "UpdateAudienceAdsBidAdjustment": True, "AdGroups": [ + {"Id": "11", "CpcBid": {"Amount": 10.0}, "Network": "OwnedAndOperatedOnly", "AudienceAdsBidAdjustment": -100}]} + assert "exceeds maximum" in manage.update_microsoft_ad_group(config, ad_group_id="11", cpc_bid=30)["error"] + auto = manage.update_microsoft_ad_group(config, ad_group_id="21", cpc_bid=4) + assert any("ignores the ad group's default bid" in w for w in auto["warnings"]) + + def test_keywords_skip_duplicates_and_refuse_broad_on_manual(self, api, config): + preview = manage.draft_microsoft_keywords(config, ad_group_id="11", keywords=[ + "drain cleaning", {"text": "Drain Cleaning", "match_type": "Exact"}, "clogged drain", "clogged drain"]) + assert any("already in the ad group" in w for w in preview["warnings"]) + _apply(config, preview) + sent = _last(api, "Keywords", "POST")["body"]["Keywords"] + assert [(k["Text"], k["MatchType"]) for k in sent] == [("Drain Cleaning", "Exact"), ("clogged drain", "Phrase")] + assert "already in the ad group" in manage.draft_microsoft_keywords(config, ad_group_id="11", keywords=["drain cleaning"])["error"] + assert "Broad match" in _text(manage.draft_microsoft_keywords(config, ad_group_id="11", keywords=[{"text": "x", "match_type": "broad"}])) + assert "1–100" in _text(manage.draft_microsoft_keywords(config, ad_group_id="11", keywords=["k" * 101])) + paused = manage.draft_microsoft_keywords(config, ad_group_id="12", keywords=["tankless"]) + assert any("Paused" in w for w in paused["warnings"]) + + def test_keyword_bids(self, api, config): + preview = manage.update_microsoft_keyword_bids(config, ad_group_id="11", bids=[ + {"keyword_id": "101", "bid": 12}, {"keyword_id": "102", "bid": None}]) + shown = {b["keyword"]: b for b in preview["changes"]["bids"]} + assert shown["drain cleaning [Phrase]"]["from"] == 8.0 # ad group default applies today + assert shown["plumber [Broad]"]["to"] == "ad group default 8.0" + _apply(config, preview) + assert _last(api, "Keywords", "PUT")["body"] == {"AdGroupId": "11", "Keywords": [ + {"Id": "101", "Bid": {"Amount": 12.0}}, {"Id": "102", "Bid": {"Amount": None}}]} + assert "exceeds maximum" in manage.update_microsoft_keyword_bids(config, ad_group_id="11", bids=[{"keyword_id": "101", "bid": 40}])["error"] + assert "not in ad group" in _text(manage.update_microsoft_keyword_bids(config, ad_group_id="11", bids=[{"keyword_id": "103", "bid": 5}])) + + def test_keyword_bid_changed_after_the_draft(self, api, config): + preview = manage.update_microsoft_keyword_bids(config, ad_group_id="11", bids=[{"keyword_id": "102", "bid": 10}]) + api.keywords["102"]["Bid"] = {"Amount": 11.0} + result = ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=False) + assert "bid changed since the draft" in result["error"] + + +# --------------------------------------------------------------------------- +# Negative keywords +# --------------------------------------------------------------------------- + + +class TestNegatives: + def test_read_lists_direct_and_shared(self, api, config): + result = manage.get_microsoft_negative_keywords(config) + assert result["direct_negatives"][0]["remove_id"] == f"Campaign~{CAMPAIGN}~501" + junk = result["negative_keyword_lists"][0] + assert junk["attached_to"] == ["Acme Plumbing - Search"] and junk["keywords"][0]["remove_id"] == "900~9001" + assert any("shared list keeps them reusable" in i for i in result["insights"]) + + def test_direct_negatives_dedupe_and_flag_conflicts(self, api, config): + preview = manage.add_microsoft_negative_keywords(config, campaign_id=CAMPAIGN, keywords=["free", "plumber", "careers"]) + assert preview["changes"]["negatives"] == ["plumber [Phrase]", "careers [Phrase]"] + assert any("block active keywords" in w and "plumber" in w for w in preview["warnings"]) + _apply(config, preview) + assert _last(api, "EntityNegativeKeywords", "POST")["body"] == {"EntityNegativeKeywords": [ + {"EntityId": int(CAMPAIGN), "EntityType": "Campaign", + "NegativeKeywords": [{"Text": "plumber", "MatchType": "Phrase"}, {"Text": "careers", "MatchType": "Phrase"}]}]} + assert "exactly one" in _text(manage.add_microsoft_negative_keywords(config, keywords=["x"])) + assert "Broad" not in manage.NEGATIVE_MATCH_TYPES + assert "match_type for negatives" in _text(manage.add_microsoft_negative_keywords(config, campaign_id=CAMPAIGN, keywords=["x"], match_type="Broad")) + + def test_new_list_is_created_then_attached(self, api, config): + preview = manage.propose_microsoft_negative_keyword_list(config, list_name="Jobs and DIY", keywords=["hiring", "apprentice"], + campaign_ids=[CAMPAIGN, "600"]) + result = _apply(config, preview) + create = _last(api, "SharedEntity")["body"] + assert create == {"SharedEntity": {"Type": "NegativeKeywordList", "Name": "Jobs and DIY"}, "SharedEntityScope": "Account", + "ListItems": [{"Type": "NegativeKeyword", "Text": "hiring", "MatchType": "Phrase"}, + {"Type": "NegativeKeyword", "Text": "apprentice", "MatchType": "Phrase"}]} + attach = _last(api, "SharedEntityAssociations/Set")["body"] + assert attach["Associations"][0] == {"EntityId": int(CAMPAIGN), "EntityType": "Campaign", + "SharedEntityId": int(result["list_id"]), "SharedEntityType": "NegativeKeywordList"} + + def test_list_guards_and_partial_failure(self, api, config): + assert "already exists" in _text(manage.propose_microsoft_negative_keyword_list(config, list_name="junk", keywords=["x"])) + api.associations += [{"SharedEntityId": 1000 + i, "EntityId": 600} for i in range(20)] + assert "20 lists" in _text(manage.propose_microsoft_negative_keyword_list(config, list_name="More", keywords=["x"], campaign_ids=["600"])) + unattached = manage.propose_microsoft_negative_keyword_list(config, list_name="Loose", keywords=["x"]) + assert any("blocks nothing until attached" in w for w in unattached["warnings"]) + preview = manage.propose_microsoft_negative_keyword_list(config, list_name="Halfway", keywords=["x"], campaign_ids=[CAMPAIGN]) + api.fail[("POST", "SharedEntityAssociations/Set")] = MicrosoftAdsApiError("boom", status=400) + result = ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=False) + assert result["status"] == "PARTIAL_APPLY" and "created list" in result["error"] and "boom" in result["error"] + del api.fail[("POST", "SharedEntityAssociations/Set")] + assert "No pending plan" in ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=False)["error"] + + def test_append_to_list_skips_existing(self, api, config): + preview = manage.add_to_microsoft_negative_keyword_list(config, list_id="900", keywords=["jobs", "salary"], match_type="Exact") + assert preview["changes"]["negatives"] == ["jobs [Exact]", "salary [Exact]"] # Exact differs from the Phrase item + _apply(config, preview) + body = _last(api, "ListItems", "POST")["body"] + assert body["SharedList"] == {"Type": "NegativeKeywordList", "Id": 900} + assert "already in the list" in manage.add_to_microsoft_negative_keyword_list(config, list_id="900", keywords=["jobs"])["error"] + assert "was not found" in manage.add_to_microsoft_negative_keyword_list(config, list_id="1", keywords=["x"])["error"] + + def test_attach_and_detach(self, api, config): + attach = manage.attach_microsoft_negative_keyword_list(config, list_id="900", campaign_ids=[CAMPAIGN, "600"]) + assert attach["changes"]["campaign_ids"] == ["600"] + _apply(config, attach) + detach = manage.detach_microsoft_negative_keyword_list(config, list_id="900", campaign_ids=[CAMPAIGN]) + _apply(config, detach) + assert _last(api, "SharedEntityAssociations", "DELETE")["body"]["Associations"][0]["EntityId"] == int(CAMPAIGN) + assert {a["EntityId"] for a in api.associations if a["SharedEntityId"] == 900} == {600} + assert "already detached" in manage.detach_microsoft_negative_keyword_list(config, list_id="900", campaign_ids=[CAMPAIGN])["error"] + + +# --------------------------------------------------------------------------- +# Responsive search ads +# --------------------------------------------------------------------------- + + +_HEADLINES = ["Drain Cleaning From $69", "Same-Day Plumbers", "Licensed & Insured", "Springfield Drain Experts", + "Upfront Pricing", "Call Acme Plumbing", "Camera Inspections", "Local Since 2008"] + + +class TestResponsiveSearchAds: + def test_create_paused_with_pins_normalised(self, api, config): + heads = [{"text": _HEADLINES[0], "pinned_field": "HEADLINE_1"}] + _HEADLINES[1:] + preview = manage.draft_microsoft_responsive_search_ad(config, ad_group_id="11", headlines=heads, + descriptions=["Licensed plumbers, upfront prices.", "Book online today."], + final_url="https://example.com/drain", path1="drain", path2="cleaning") + assert any("pinned" in w for w in preview["warnings"]) + _apply(config, preview) + ad = _last(api, "Ads", "POST")["body"]["Ads"][0] + assert ad["Type"] == "ResponsiveSearch" and ad["Status"] == "Paused" + assert ad["Headlines"][0] == {"Asset": {"Type": "TextAsset", "Text": _HEADLINES[0]}, "PinnedField": "Headline1"} + assert ad["Descriptions"][1] == {"Asset": {"Type": "TextAsset", "Text": "Book online today."}} + assert ad["FinalUrls"] == ["https://example.com/drain"] and (ad["Path1"], ad["Path2"]) == ("drain", "cleaning") + + def test_validation(self, api, config): + bad = manage.draft_microsoft_responsive_search_ad( + config, ad_group_id="11", headlines=["x" * 31, "Same", "Same"], descriptions=["only one"], + final_url="https://example.com/drain", path1="a/b") + text = _text(bad) + for fragment in ("1–30 characters", "repeat the same text", "2–4 descriptions", "without '/'"): + assert fragment in text + unfillable = manage.draft_microsoft_responsive_search_ad( + config, ad_group_id="11", headlines=[{"text": h, "pinned_field": "HEADLINE_1"} for h in _HEADLINES[:3]], + descriptions=["One.", "Two."], final_url="https://example.com/drain") + assert "Nothing can fill Headline2" in _text(unfillable) + assert "path2 needs path1" in _text(manage.draft_microsoft_responsive_search_ad( + config, ad_group_id="11", headlines=_HEADLINES[:3], descriptions=["One.", "Two."], + final_url="https://example.com/drain", path2="x")) + + def test_unreachable_landing_page(self, api, config, monkeypatch): + monkeypatch.setattr("adloop.ads.write._validate_urls", lambda urls, timeout=10: ({u: "HTTP 404" for u in urls}, {})) + result = manage.draft_microsoft_responsive_search_ad(config, ad_group_id="11", headlines=_HEADLINES[:3], + descriptions=["One.", "Two."], final_url="https://example.com/gone") + assert "not reachable" in _text(result) + + def test_identical_ad_is_refused_at_dry_run(self, api, config): + preview = manage.draft_microsoft_responsive_search_ad(config, ad_group_id="11", headlines=["Drain Cleaning", "Same Day", "Call Now"], + descriptions=["Licensed.", "Local."], final_url="https://example.com/drain") + dry = ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=True) + assert dry["status"] == "DRY_RUN_FAILED" and "already has an RSA" in dry["error"] + + def test_update_replaces_only_the_lists_given(self, api, config): + preview = manage.update_microsoft_responsive_search_ad(config, ad_id="301", headlines=_HEADLINES[:4], path2="") + assert preview["changes"]["changes"]["headlines"]["from"] == ["Drain Cleaning", "Same Day", "Call Now"] + assert any("editorial review" in w for w in preview["warnings"]) + _apply(config, preview) + update = _last(api, "Ads", "PUT")["body"] + assert update["AdGroupId"] == "11" and set(update["Ads"][0]) == {"Type", "Id", "Headlines", "Path2"} + assert update["Ads"][0]["Path2"] == "" + assert "Nothing to change" in manage.update_microsoft_responsive_search_ad(config, ad_id="301")["error"] + + +# --------------------------------------------------------------------------- +# Extensions +# --------------------------------------------------------------------------- + + +class TestExtensions: + def test_sitelinks_created_and_linked_to_the_campaign(self, api, config): + preview = manage.draft_microsoft_sitelinks(config, campaign_id=CAMPAIGN, sitelinks=[ + {"link_text": "Drain Cleaning", "final_url": "https://example.com/drain"}, # already linked + {"link_text": "Water Heaters", "final_url": "https://example.com/water-heaters", + "description1": "Same-day installs", "description2": "Tank and tankless"}, + ]) + joined = " ".join(preview["warnings"]) + assert "Skipped 1" in joined and "Four or more" in joined + result = _apply(config, preview) + created = _last(api, "AdExtensions")["body"] + assert created == {"AccountId": ACCOUNT, "AdExtensions": [{ + "Type": "SitelinkAdExtension", "DisplayText": "Water Heaters", "FinalUrls": ["https://example.com/water-heaters"], + "Description1": "Same-day installs", "Description2": "Tank and tankless"}]} + link = _last(api, "AdExtensionsAssociations/Set")["body"] + assert link["AssociationType"] == "Campaign" + assert link["AdExtensionIdToEntityIdAssociations"] == [{"AdExtensionId": int(result["extension_ids"][0]), "EntityId": int(CAMPAIGN)}] + + def test_sitelink_rules(self, api, config): + bad = manage.draft_microsoft_sitelinks(config, campaign_id=CAMPAIGN, sitelinks=[ + {"link_text": "A very long sitelink text here", "final_url": "https://x.com", "description1": "d"}, + ]) + text = _text(bad) + assert "1–25 characters" in text and "both descriptions or neither" in text + + def test_account_scope_links_to_the_account(self, api, config): + preview = manage.draft_microsoft_callouts(config, scope="account", callouts=["Licensed", "Upfront Pricing"]) + _apply(config, preview) + link = _last(api, "AdExtensionsAssociations/Set")["body"] + assert link["AssociationType"] == "Account" and link["AdExtensionIdToEntityIdAssociations"][0]["EntityId"] == int(ACCOUNT) + assert "not both" in _text(manage.draft_microsoft_callouts(config, campaign_id=CAMPAIGN, scope="account", callouts=["x"])) + + def test_callout_and_snippet_rules(self, api, config): + assert "longer than 25" in _text(manage.draft_microsoft_callouts(config, campaign_id=CAMPAIGN, callouts=["x" * 26])) + one = manage.draft_microsoft_callouts(config, campaign_id="600", callouts=["24/5 Service"]) + assert any("at least 2 callouts" in w for w in one["warnings"]) + assert "already on" in manage.draft_microsoft_callouts(config, campaign_id=CAMPAIGN, callouts=["Licensed"])["error"] + assert "3–10 values" in _text(manage.draft_microsoft_structured_snippet(config, campaign_id=CAMPAIGN, header="Services", values=["a", "b"])) + snippet = manage.draft_microsoft_structured_snippet(config, campaign_id=CAMPAIGN, header="Services", + values=["Drain Cleaning", "Water Heaters", "Repiping"]) + assert snippet["changes"]["extensions"][0] == {"Type": "StructuredSnippetAdExtension", "Header": "Services", + "Values": ["Drain Cleaning", "Water Heaters", "Repiping"]} + + def test_one_call_extension_per_campaign(self, api, config): + preview = manage.draft_microsoft_call_extension(config, campaign_id=CAMPAIGN, phone_number="(217) 555-0100", country_code="us") + assert preview["changes"]["extensions"][0] == {"Type": "CallAdExtension", "PhoneNumber": "(217) 555-0100", + "CountryCode": "US", "IsCallOnly": False} + _apply(config, preview) + again = manage.draft_microsoft_call_extension(config, campaign_id=CAMPAIGN, phone_number="(217) 555-0199", country_code="US") + assert "already has a call extension" in _text(again) + assert "two-letter" in _text(manage.draft_microsoft_call_extension(config, campaign_id="600", phone_number="1", country_code="USA")) + + def test_read_extensions(self, api, config): + result = manage.get_microsoft_ad_extensions(config) + rows = {r["content"]: r for r in result["extensions"]} + assert rows["Drain Cleaning"]["type"] == "Sitelink" and rows["Drain Cleaning"]["remove_id"] == f"7001~{CAMPAIGN}~Campaign" + assert any("'Brand' has no sitelinks" in i for i in result["insights"]) + + +# --------------------------------------------------------------------------- +# Removal +# --------------------------------------------------------------------------- + + +class TestRemoval: + @pytest.mark.parametrize("entity_type,entity_id,path,body", [ + ("keyword", "102", "Keywords", {"AdGroupId": "11", "KeywordIds": ["102"]}), + ("ad", "301", "Ads", {"AdGroupId": "11", "AdIds": ["301"]}), + ("ad_group", "12", "AdGroups", {"CampaignId": CAMPAIGN, "AdGroupIds": ["12"]}), + ("campaign", "600", "Campaigns", {"AccountId": ACCOUNT, "CampaignIds": ["600"]}), + ("negative_keyword", f"Campaign~{CAMPAIGN}~501", "EntityNegativeKeywords", {"EntityNegativeKeywords": [ + {"EntityId": int(CAMPAIGN), "EntityType": "Campaign", "NegativeKeywords": [{"Id": 501}]}]}), + ("negative_list_item", "900~9001", "ListItems", {"ListItemIds": [9001], "SharedList": {"Type": "NegativeKeywordList", "Id": 900}, + "SharedEntityScope": "Account"}), + ("campaign_criterion", f"{CAMPAIGN}~1002", "CampaignCriterions", {"CampaignCriterionIds": [1002], "CampaignId": int(CAMPAIGN), + "CriterionType": "Targets"}), + ("extension_association", f"7001~{CAMPAIGN}~Campaign", "AdExtensionsAssociations", { + "AccountId": ACCOUNT, "AssociationType": "Campaign", + "AdExtensionIdToEntityIdAssociations": [{"AdExtensionId": 7001, "EntityId": int(CAMPAIGN)}]}), + ]) + def test_each_removal_sends_its_delete(self, api, config, entity_type, entity_id, path, body): + preview = manage.remove_microsoft_entity(config, entity_type=entity_type, entity_id=entity_id) + assert preview["requires_double_confirm"] is True and preview["operation"] == "microsoft_remove_entity" + _apply(config, preview) + call = _last(api, path, "DELETE") + assert call["body"] == body + + def test_bad_ids(self, api, config): + assert "entity_id format" in _text(manage.remove_microsoft_entity(config, entity_type="negative_keyword", entity_id="501")) + assert "was not found" in manage.remove_microsoft_entity(config, entity_type="keyword", entity_id="999")["error"] + assert "entity_type must be one of" in _text(manage.remove_microsoft_entity(config, entity_type="account", entity_id="1")) + + def test_entity_gone_before_apply(self, api, config): + preview = manage.remove_microsoft_entity(config, entity_type="keyword", entity_id="102") + api.keywords.pop("102") + result = ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=False) + assert "no longer exists" in result["error"] + + +# --------------------------------------------------------------------------- +# Location search and the gate +# --------------------------------------------------------------------------- + + +_GEO_CSV = ( + "Location Id,Bing Display Name,Location Type,Status\n" + "190,\"Springfield, Illinois, United States\",City,Active\n" + "191,\"Springfield County, California, United States\",County,Active\n" + "192,\"West Springfield, Illinois, United States\",City,PendingDeprecation\n" + "200,\"Davis, California, United States\",City,Active\n" +).encode() + + +class _File: + def __init__(self, content, status=200): + self.content = content + self.status_code = status + + +class TestLocationsAndGate: + def test_search_downloads_once_and_ranks(self, api, config, tmp_path, monkeypatch): + monkeypatch.setattr(read, "_geo_cache_path", lambda: tmp_path / "geo.csv") + with patch("requests.get", return_value=_File(gzip.compress(_GEO_CSV))) as get: + first = read.search_microsoft_locations(config, query="springfield") + read.search_microsoft_locations(config, query="davis") + assert get.call_count == 1 + names = [r["name"] for r in first["locations"]] + assert names[0].startswith("Springfield,") and names[-1].startswith("West Springfield") + assert first["locations"][0]["location_id"] == "190" + cities = read.search_microsoft_locations(config, query="springfield", location_type="county") + assert [r["location_id"] for r in cities["locations"]] == ["191"] + # A fresh process reads the cached file instead of downloading again. + read._GEO_CACHE.clear() + with patch("requests.get", side_effect=AssertionError("no download")): + assert read.search_microsoft_locations(config, query="davis")["total_matches"] == 1 + + def test_download_error_hides_the_link(self, api, config, tmp_path, monkeypatch): + import requests + + monkeypatch.setattr(read, "_geo_cache_path", lambda: tmp_path / "geo.csv") + with patch("requests.get", side_effect=requests.ConnectionError("https://geo.example/locations.csv.gz?sig=SECRET")): + with pytest.raises(MicrosoftAdsApiError) as err: + read.search_microsoft_locations(config, query="davis") + assert "SECRET" not in str(err.value) + + def test_two_phase_apply_and_blocked_operations(self, api, config): + config.safety.two_phase_apply = True + preview = manage.draft_microsoft_callouts(config, campaign_id="600", callouts=["Licensed", "Insured"]) + assert ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=False)["status"] == "DRY_RUN_REQUIRED" + assert not [c for c in api.calls if c["path"] == "AdExtensions"] + config.safety.blocked_operations = ["microsoft_remove_entity"] + assert "blocked" in manage.remove_microsoft_entity(config, entity_type="keyword", entity_id="101")["error"] + + def test_server_tools_return_previews(self, api, config): + from adloop import runtime, server + + runtime.set_default_config(config) + try: + preview = server.draft_microsoft_keywords(ad_group_id="11", keywords=["clogged drain"]) + assert preview["status"] == "PENDING_CONFIRMATION" and preview["platform"] == "microsoft" + assert server.get_microsoft_negative_keywords()["negative_keyword_lists"][0]["name"] == "Junk" + finally: + runtime.set_default_config(None) + + +class TestRoundThreeFindings: + """Codex review round three (adloop-audit-2026-11-04.md), Microsoft findings 4–7.""" + + def _no_put(self, api, path): + return not [c for c in api.calls if c["path"] == path and c["method"] in ("PUT", "POST")] + + # -- finding 4: effective bids, at draft and at apply + def test_cap_lowered_after_the_dry_run_refuses_the_bid_raise(self, api, config): + preview = manage.update_microsoft_ad_group(config, ad_group_id="11", cpc_bid=12) + assert ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=True)["status"] == "DRY_RUN_SUCCESS" + config.safety.max_bid_increase_pct = 0 + result = ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=False) + assert result.get("status") != "APPLIED" and "exceeds maximum" in _text(result) + assert self._no_put(api, "AdGroups") and api.ad_groups["11"]["CpcBid"] == {"Amount": 8.0} + + def test_keyword_bid_raise_rechecked_against_the_cap_at_apply(self, api, config): + preview = manage.update_microsoft_keyword_bids(config, ad_group_id="11", bids=[{"keyword_id": "102", "bid": 12}]) + config.safety.max_bid_increase_pct = 10 + result = ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=False) + assert result.get("status") != "APPLIED" and "exceeds maximum" in _text(result) + assert self._no_put(api, "Keywords") + + def test_removing_an_override_is_capped_by_the_inherited_bid(self, api, config): + # A $1 keyword bid removed inherits the $8 default: an 700% raise. + api.keywords["102"]["Bid"] = {"Amount": 1.0} + result = manage.update_microsoft_keyword_bids(config, ad_group_id="11", bids=[{"keyword_id": "102", "bid": None}]) + assert "plan_id" not in result and "exceeds maximum" in _text(result) + + def test_default_bid_changed_after_the_preview_refuses_the_inheriting_keyword(self, api, config): + preview = manage.update_microsoft_keyword_bids(config, ad_group_id="11", bids=[{"keyword_id": "102", "bid": None}]) + assert "plan_id" in preview # $9 → inherits $8 + api.ad_groups["11"]["CpcBid"] = {"Amount": 80.0} + result = ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=False) + assert result.get("status") != "APPLIED" and "default bid changed since the draft" in _text(result) + assert self._no_put(api, "Keywords") and api.keywords["102"]["Bid"] == {"Amount": 9.0} + + # -- finding 5: broad match re-checked at apply + def test_campaign_switched_to_manual_after_the_dry_run_refuses_broad_keywords(self, api, config): + preview = manage.draft_microsoft_keywords(config, ad_group_id="21", keywords=[{"text": "acme plumbers", "match_type": "Broad"}]) + assert ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=True)["status"] == "DRY_RUN_SUCCESS" + api.campaigns["600"]["BiddingScheme"] = {"Type": "ManualCpc"} + result = ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=False) + assert result.get("status") != "APPLIED" and "Broad match" in _text(result) + assert self._no_put(api, "Keywords") + + def test_campaign_switched_to_manual_refuses_a_new_ad_group_with_broad_keywords(self, api, config): + preview = manage.draft_microsoft_ad_group(config, campaign_id="600", name="Auto", + keywords=[{"text": "acme", "match_type": "Broad"}]) + api.campaigns["600"]["BiddingScheme"] = {"Type": "ManualCpc"} + result = ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=False) + assert result.get("status") != "APPLIED" + assert "Broad match" in _text(result) and "needs a default bid" in _text(result) + assert self._no_put(api, "AdGroups") + + def test_broad_keyword_added_before_a_pending_manual_switch_refuses_it(self, api, config): + preview = manage.update_microsoft_campaign(config, campaign_id="600", bidding_strategy="ManualCpc") + assert "plan_id" in preview, preview + api.keywords["299"] = {"Id": 299, "Text": "acme plumbers", "MatchType": "Broad", "Bid": {"Amount": None}, + "Status": "Active", "_group": "21"} + result = ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=False) + assert result.get("status") != "APPLIED" and "broad-match" in _text(result) + assert not [c for c in api.calls if c["path"] == "Campaigns" and c["method"] == "PUT"] + + # -- finding 6: every bid and line of copy is on the approval surfaces + def test_dialog_shows_keyword_bid_overrides(self, api, config): + from adloop.safety.approval import confirmation_message, display_fields + + preview = manage.draft_microsoft_ad_group(config, campaign_id=CAMPAIGN, name="Sewer", cpc_bid=5, + keywords=[{"text": "sewer line", "match_type": "exact", "bid": 25}]) + plan = preview_store.get_plan(preview["plan_id"]) + shown = _text(dict(display_fields(plan.changes))) + assert "sewer line [Exact] bid 25.0" in shown and "keyword_rows" not in shown + assert "bid 25.0" in confirmation_message(plan) + + def test_dialog_shows_sitelink_descriptions(self, api, config): + from adloop.safety.approval import confirmation_message, display_fields + + preview = manage.draft_microsoft_sitelinks(config, campaign_id="600", sitelinks=[ + {"link_text": "Water Heaters", "final_url": "https://example.com/water-heaters", + "description1": "Same-day installs", "description2": "Tank and tankless"}]) + plan = preview_store.get_plan(preview["plan_id"]) + shown = _text(dict(display_fields(plan.changes))) + assert "Same-day installs / Tank and tankless" in shown and '"extensions"' not in shown + assert "Tank and tankless" in confirmation_message(plan) + + # -- finding 7: a partial create keeps its IDs and is never replayed + def test_partial_extension_create_reports_ids_and_retires_the_plan(self, api, config): + preview = manage.draft_microsoft_callouts(config, campaign_id="600", callouts=["Upfront Pricing", "Bad Callout"]) + original = api.__call__ + + def partial(cfg, service, path, body=None, **kw): + if path == "AdExtensions": + first = {**body, "AdExtensions": body["AdExtensions"][:1]} + done = original(cfg, service, path, first, **kw) + return {"AdExtensionIdentities": [done["AdExtensionIdentities"][0], None], + "NestedPartialErrors": [{"Index": 1, "BatchErrors": [ + {"Index": 0, "ErrorCode": "CampaignServiceInvalidAdExtensionText", "Message": "Invalid callout text."}]}]} + return original(cfg, service, path, body, **kw) + + with patch("adloop.microsoft_ads.client.ms_request", side_effect=partial): + result = ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=False) + again = ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=False) + assert result["status"] == "PARTIAL_APPLY", result + created = [i for ids in result["created"].values() for i in ids] + assert len(created) == 1 and created[0] in api.extensions + assert "Invalid callout text" in result["error"] + assert "No pending plan" in _text(again) + assert sum(1 for e in api.extensions.values() if e.get("Text") == "Upfront Pricing") == 1 + + +class TestUpstreamAuditFindings: + """Codex audit of the upstream ports (adloop-audit-2026-11-04-upstream.md), Microsoft findings.""" + + @staticmethod + def _window(api, crit_id, day, start, end, campaign=CAMPAIGN): + api.criteria[campaign].append({"Id": crit_id, "Type": "BiddableCampaignCriterion", "CampaignId": int(campaign), + "Criterion": {"Type": "DayTime", "Day": day, "FromHour": start, "FromMinute": "Zero", + "ToHour": end, "ToMinute": "Zero"}}) + + def _schedule(self, api): + return sorted((c["Criterion"]["Day"], c["Criterion"]["FromHour"], c["Criterion"]["ToHour"]) + for c in api.criteria[CAMPAIGN] if c["Criterion"]["Type"] == "DayTime") + + # -- finding 2: target CPA is read, shown and pinned + def test_target_cpa_is_shown_and_a_later_change_blocks_the_apply(self, api, config): + api.campaigns["600"]["BiddingScheme"] = {"Type": "MaxConversions", "TargetCpa": 30.0} + preview = manage.update_microsoft_campaign(config, campaign_id="600", target_cpa=40) + assert "30" in _text(preview["changes"]["changes"]["bidding"]["from"]) + assert ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=True)["status"] == "DRY_RUN_SUCCESS" + api.campaigns["600"]["BiddingScheme"]["TargetCpa"] = 60.0 + result = ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=False) + assert result.get("status") != "APPLIED" and "BiddingScheme changed since the draft" in _text(result) + assert api.campaigns["600"]["BiddingScheme"]["TargetCpa"] == 60.0 + + # -- finding 4: whose clock the schedule follows + def test_searcher_time_zone_schedules_say_so(self, api, config): + api.campaigns[CAMPAIGN]["AdScheduleUseSearcherTimeZone"] = True + preview = manage.update_microsoft_campaign_targeting( + config, campaign_id=CAMPAIGN, ad_schedule=[{"day_of_week": "Monday", "start_hour": 9, "end_hour": 17}]) + assert preview["changes"]["changes"]["ad_schedule"]["hours_in"] == "each searcher's own time zone" + assert any("each searcher's own time zone" in w for w in preview["warnings"]) + assert not any("not the searcher's" in w for w in preview["warnings"]) + + def test_time_zone_mode_changed_after_the_preview_blocks_the_apply(self, api, config): + preview = manage.update_microsoft_campaign_targeting( + config, campaign_id=CAMPAIGN, ad_schedule=[{"day_of_week": "Monday", "start_hour": 9, "end_hour": 17}]) + assert "account time zone" in preview["changes"]["changes"]["ad_schedule"]["hours_in"] + api.campaigns[CAMPAIGN]["AdScheduleUseSearcherTimeZone"] = True + result = ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=False) + assert result.get("status") != "APPLIED" and "AdScheduleUseSearcherTimeZone" in _text(result) + assert self._schedule(api) == [] + + # -- finding 5: replacing windows Microsoft will accept + def test_overlapping_replacement_deletes_before_it_adds(self, api, config): + self._window(api, 7001, "Monday", 9, 17) + preview = manage.update_microsoft_campaign_targeting( + config, campaign_id=CAMPAIGN, ad_schedule=[{"day_of_week": "Monday", "start_hour": 10, "end_hour": 18}]) + assert any("no schedule and serves at all hours" in w for w in preview["warnings"]) + _apply(config, preview) + methods = [c["method"] for c in api.calls if c["path"] == "CampaignCriterions" and c["method"] != "GET" + and "QueryByIds" not in c["path"]] + assert methods == ["DELETE", "POST"] + assert self._schedule(api) == [("Monday", 10, 18)] + + def test_unchanged_windows_stay_and_disjoint_ones_go_in_first(self, api, config): + self._window(api, 7001, "Monday", 9, 17) + self._window(api, 7002, "Tuesday", 9, 12) + preview = manage.update_microsoft_campaign_targeting(config, campaign_id=CAMPAIGN, ad_schedule=[ + {"day_of_week": "Monday", "start_hour": 9, "end_hour": 17}, # kept + {"day_of_week": "Tuesday", "start_hour": 13, "end_hour": 17}, # no overlap: first + ]) + ops = preview["changes"]["operations"] + assert len(ops["schedule_add_first"]) == 1 and ops["schedule_delete"] == ["7002"] and ops["schedule_add_after"] == [] + assert not any("serves at all hours" in w for w in preview["warnings"]) + _apply(config, preview) + assert self._schedule(api) == [("Monday", 9, 17), ("Tuesday", 13, 17)] + assert not any(c["method"] == "DELETE" and 7001 in (c["body"].get("CampaignCriterionIds") or []) for c in api.calls) + + def test_identical_schedule_is_nothing_to_change(self, api, config): + self._window(api, 7001, "Monday", 9, 17) + result = manage.update_microsoft_campaign_targeting( + config, campaign_id=CAMPAIGN, ad_schedule=[{"day_of_week": "Monday", "start_hour": 9, "end_hour": 17}]) + assert "already matches" in result["error"] + + def test_failure_after_the_old_windows_are_gone_is_reported(self, api, config): + self._window(api, 7001, "Monday", 9, 17) + preview = manage.update_microsoft_campaign_targeting( + config, campaign_id=CAMPAIGN, ad_schedule=[{"day_of_week": "Monday", "start_hour": 10, "end_hour": 18}]) + api.fail[("POST", "CampaignCriterions")] = MicrosoftAdsApiError("Internal error", status=400) + result = ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=False) + assert result["status"] == "PARTIAL_APPLY", result + assert "serves at all hours" in result["error"] and "removed 1 schedule window" in result["error"] + assert self._schedule(api) == [] + + # -- finding 3: a create whose answer was lost is never replayed + @pytest.mark.parametrize("draft", [ + lambda: manage.draft_microsoft_callouts(CFG[0], campaign_id="600", callouts=["Upfront Pricing", "Licensed Pros"]), + lambda: manage.draft_microsoft_keywords(CFG[0], ad_group_id="11", keywords=["clogged drain"]), + lambda: manage.propose_microsoft_negative_keyword_list(CFG[0], list_name="Jobs", keywords=["careers"], + campaign_ids=["600"]), + ]) + def test_lost_create_response_retires_the_plan(self, api, config, draft): + CFG[0] = config + preview = draft() + assert "plan_id" in preview, preview + original = api.__call__ + + def lose(cfg, service, path, body=None, **kw): + result = original(cfg, service, path, body, **kw) + if kw.get("method", "POST") == "POST" and path in ("AdExtensions", "Keywords", "SharedEntity"): + raise MicrosoftAdsApiError("Could not reach Microsoft Advertising (ReadTimeout); " + "the change may or may not have been made.") + return result + + with patch("adloop.microsoft_ads.client.ms_request", side_effect=lose): + first = ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=False) + again = ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=False) + assert first["status"] == "UNKNOWN_OUTCOME", first + assert "No pending plan" in _text(again) + + +CFG = [None] + + +class TestKeywordStatusOnCreate: + """Finding 9: the approval surfaces say keywords are created Active.""" + + def test_keywords_in_a_live_ad_group_say_they_serve_immediately(self, api, config): + from adloop.safety.approval import display_fields + + preview = manage.draft_microsoft_keywords(config, ad_group_id="11", keywords=["clogged drain"]) + shown = dict(display_fields(preview_store.get_plan(preview["plan_id"]).changes)) + assert shown["status_on_create"] == "Active" + assert shown["ad_group_status"] == "Active" and shown["campaign_status"] == "Active" + assert any("can serve as soon as this is applied" in w for w in preview["warnings"]) + + def test_keywords_in_a_paused_ad_group_say_when_they_serve(self, api, config): + preview = manage.draft_microsoft_keywords(config, ad_group_id="12", keywords=["tankless"]) + assert preview["changes"]["ad_group_status"] == "Paused" + assert any("serve once both are active" in w for w in preview["warnings"]) + assert not any("as soon as this is applied" in w for w in preview["warnings"]) + + def test_a_new_ad_group_states_its_status(self, api, config): + preview = manage.draft_microsoft_ad_group(config, campaign_id=CAMPAIGN, name="Sewer", cpc_bid=5, + keywords=["sewer line"]) + assert preview["changes"]["status_on_create"].startswith("Active") + + +class TestScheduleDeltaFindings: + """Codex delta audit (adloop-audit-2026-11-04-delta.md): findings 2, 4 and 7.""" + + _window = staticmethod(TestUpstreamAuditFindings._window) + _schedule = TestUpstreamAuditFindings._schedule + + def test_six_disjoint_windows_replaced_by_six_others_stay_within_seven_a_day(self, api, config): + # Finding 4: adding all six new windows first would ask for twelve on Monday. + for i, start in enumerate(range(0, 12, 2)): + self._window(api, 7100 + i, "Monday", start, start + 1) + new = [{"day_of_week": "Monday", "start_hour": h, "end_hour": h + 1} for h in range(12, 24, 2)] + preview = manage.update_microsoft_campaign_targeting(config, campaign_id=CAMPAIGN, ad_schedule=new) + ops = preview["changes"]["operations"] + assert len(ops["schedule_add_first"]) == 1 and len(ops["schedule_add_after"]) == 5 + assert not any("serves at all hours" in w for w in preview["warnings"]) + _apply(config, preview) + assert self._schedule(api) == [("Monday", h, h + 1) for h in range(12, 24, 2)] + + def test_a_failure_names_the_windows_that_stay(self, api, config): + # Finding 7: Monday is kept, so the campaign is not unscheduled. + self._window(api, 7001, "Monday", 9, 17) + self._window(api, 7002, "Tuesday", 9, 17) + preview = manage.update_microsoft_campaign_targeting(config, campaign_id=CAMPAIGN, ad_schedule=[ + {"day_of_week": "Monday", "start_hour": 9, "end_hour": 17}, + {"day_of_week": "Tuesday", "start_hour": 10, "end_hour": 18}]) + api.fail[("POST", "CampaignCriterions")] = MicrosoftAdsApiError("Internal error", status=400) + result = ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=False) + assert result["status"] == "PARTIAL_APPLY", result + assert "keeps Mon 09:00–17:00" in result["error"] and "serves at all hours" not in result["error"] + assert self._schedule(api) == [("Monday", 9, 17)] + + @pytest.mark.parametrize("with_locations", [False, True]) + def test_a_schedule_plan_from_before_the_fix_must_be_drafted_again(self, api, config, with_locations): + # Finding 2: the old plan shape put schedule windows in add/delete and + # carried no time zone mode; it is refused, never applied the old way. + self._window(api, 7001, "Monday", 9, 17) + preview = manage.update_microsoft_campaign_targeting( + config, campaign_id=CAMPAIGN, location_ids=["190", "200"] if with_locations else None, + ad_schedule=[{"day_of_week": "Monday", "start_hour": 10, "end_hour": 18}]) + plan = preview_store.get_plan(preview["plan_id"]) + ops = plan.changes["operations"] + ops["add"] += ops.pop("schedule_add_first") + ops.pop("schedule_add_after") + ops["delete"] += ops.pop("schedule_delete") + ops.pop("schedule_kept", None) + plan.changes["before"].pop("searcher_time_zone") + preview_store.store_plan(plan) + result = ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=False) + assert result.get("status") != "APPLIED" and "draft it again" in _text(result) + assert self._schedule(api) == [("Monday", 9, 17)] + assert not [c for c in api.calls if c["path"] == "CampaignCriterions" and c["method"] in ("POST", "DELETE")] + + +class TestGoalsWithoutInStorePilot: + """The MaxConversions goal check must work for accounts outside Microsoft's in-store pilot.""" + + def test_counted_goals_are_counted(self, api, config): + api.in_store_pilot = False + assert manage._counted_goals(config, ACCOUNT, CUSTOMER) == 1 + api.goals = [] + assert manage._counted_goals(config, ACCOUNT, CUSTOMER) == 0 + + def test_max_conversions_without_goals_still_warns(self, api, config): + api.in_store_pilot = False + api.goals = [] + update = manage.update_microsoft_campaign(config, campaign_id="600", target_cpa=25) + assert any("nothing to optimize" in w for w in update["warnings"]) + new = manage.draft_microsoft_campaign(config, name="New", daily_budget=10, languages=["English"], + location_ids=["190"]) + assert any("nothing to optimize" in w for w in new["warnings"]) + + def test_an_unreadable_goal_list_is_unknown(self, api, config): + api.fail[("POST", "ConversionGoals/QueryByIds")] = MicrosoftAdsApiError("Internal error", status=500) + assert manage._counted_goals(config, ACCOUNT, CUSTOMER) == -1 + + +# --------------------------------------------------------------------------- +# Image extensions +# --------------------------------------------------------------------------- + + +def _png(width: int, height: int, *, animated: bool = False, pad: int = 0) -> bytes: + import struct + import zlib + + def chunk(kind: bytes, data: bytes) -> bytes: + return struct.pack(">I", len(data)) + kind + data + struct.pack(">I", zlib.crc32(kind + data) & 0xFFFFFFFF) + + out = b"\x89PNG\r\n\x1a\n" + chunk(b"IHDR", struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0)) + if animated: # APNG: the animation control chunk comes before the image data + out += chunk(b"acTL", struct.pack(">II", 2, 0)) + if pad: + out += chunk(b"tEXt", b"pad\x00" + b"x" * pad) + return out + chunk(b"IDAT", zlib.compress(b"\x00" * 16)) + chunk(b"IEND", b"") + + +def _jpeg(width: int, height: int) -> bytes: + import struct + + return b"\xff\xd8\xff\xc0" + struct.pack(">HBHHB", 11, 8, height, width, 1) + b"\x01\x11\x00\xff\xd9" + + +def _gif(width: int, height: int, frames: int = 1) -> bytes: + import struct + + frame = b"\x2c" + struct.pack(" str: + path = tmp_path / name + path.write_bytes(data) + return str(path) + + +class TestImageExtensions: + @pytest.fixture + def web(self, monkeypatch): + """Public image URLs served from a dict the test can change.""" + from adloop.ads.image_fetch import FetchedImage + + pages: dict[str, bytes] = {} + monkeypatch.setattr("adloop.ads.image_fetch.fetch_image_bytes", + lambda url: FetchedImage(url=url, final_url=url, data=pages[url])) + return pages + + def _image_link(self, api, ext_id: str, owner: str, association: str, alt: str = "Technician at a drain"): + api.extensions[ext_id] = {"Id": int(ext_id), "Type": "ImageAdExtension", "AlternativeText": alt, + "ImageMediaIds": [int(ext_id) + 100], "Description": "AdLoop image van", + "Layouts": ["SearchSingle"]} + api.ext_links.append((ext_id, owner, association)) + + def test_bad_images_and_fields_are_refused_with_the_reason(self, api, config, tmp_path): + good = _file(tmp_path, "van.png", _png(1200, 628)) + + def refused(**kw): + kw.setdefault("alt_text", "Plumbing van") + return _text(manage.draft_microsoft_image_extension(config, campaign_id=CAMPAIGN, **kw)) + + assert "703x368" in refused(image_paths=[_file(tmp_path, "small.png", _png(600, 314))]) + square = refused(image_paths=[_file(tmp_path, "square.jpg", _jpeg(1200, 1200))]) + assert "1.00:1" in square and "1.91:1" in square and "Crop it to 1200x628" in square + assert "maximum (width 2592, height 2048)" in refused(image_paths=[_file(tmp_path, "huge.png", _png(3000, 1571))]) + assert "animated images are not accepted" in refused(image_paths=[_file(tmp_path, "spin.gif", _gif(1200, 628, frames=2))]) + assert "animated images are not accepted" in refused(image_paths=[_file(tmp_path, "spin.png", _png(1200, 628, animated=True))]) + assert "5 MB limit" in refused(image_paths=[_file(tmp_path, "heavy.png", _png(1200, 628, pad=5 * 1024 * 1024))]) + assert "Unsupported image type" in refused(image_paths=[_file(tmp_path, "photo.bmp", b"BM" + b"\x00" * 64)]) + assert "twice" in refused(image_paths=[good, good]) + assert "alt_text is required" in refused(image_paths=[good], alt_text=" ") + assert "alt_text is 36 characters" in refused(image_paths=[good], alt_text="x" * 36) + assert "display_text is 36 characters" in refused(image_paths=[good], display_text="y" * 36) + assert "At least one image" in refused() + assert "At most 10 images" in refused(image_paths=[good] * 11) + # A still GIF at the right size passes the image checks. + still = manage.draft_microsoft_image_extension(config, campaign_id=CAMPAIGN, alt_text="Van", + image_paths=[_file(tmp_path, "still.gif", _gif(1200, 628))]) + assert "plan_id" in still, still + both = manage.draft_microsoft_image_extension(config, campaign_id=CAMPAIGN, ad_group_id="11", alt_text="Van", + image_paths=[good]) + assert "not both" in _text(both) + assert "was not found" in _text(manage.draft_microsoft_image_extension( + config, ad_group_id="999", alt_text="Van", image_paths=[good])) + assert not [c for c in api.calls if c["path"] in ("Media", "AdExtensions")] + + def test_preview_shows_images_target_and_alt_text(self, api, config, tmp_path, web): + from adloop.safety.approval import confirmation_message + from adloop.safety.preview import get_plan + + web["https://cdn.example.com/team.jpg"] = _jpeg(1406, 736) + preview = manage.draft_microsoft_image_extension( + config, ad_group_id="11", image_paths=[_file(tmp_path, "van.png", _png(1200, 628))], + image_urls=["https://cdn.example.com/team.jpg"], alt_text="Plumber clearing a drain", + display_text="Same-day drain service", final_url="https://example.com/drain") + assert preview["operation"] == "microsoft_add_image_extension" and preview["entity_type"] == "ad_group" + changes = preview["changes"] + assert changes["entity_name"] == "ad group 'Drains' in campaign 'Acme Plumbing - Search'" + assert changes["association_type"] == "AdGroup" and changes["entity_id"] == "11" + assert changes["images"][0].endswith("PNG 1200x628 (1.91:1), 0.1 KB") + assert changes["images"][1] == "https://cdn.example.com/team.jpg: JPEG 1406x736 (1.91:1), 0.0 KB" + assert changes["alt_text"] == "Plumber clearing a drain" and changes["display_text"] == "Same-day drain service" + assert changes["final_url"] == "https://example.com/drain" + assert changes["layouts"] == ["SearchSingle", "SearchMultiple"] + warnings = " ".join(preview["warnings"]) + assert "Audience Network" in warnings and "multi-image layout" in warnings and "PNG images to JPEG" in warnings + # The approval dialog shows the images, never the pinned payloads. + message = confirmation_message(get_plan(preview["plan_id"])) + assert "1200x628" in message and "image payloads" not in message and "sha256" not in message + plain = manage.draft_microsoft_image_extension(config, campaign_id=CAMPAIGN, alt_text="Van", + image_paths=[_file(tmp_path, "van2.png", _png(1910, 1000))]) + assert plain["changes"]["layouts"] == ["SearchSingle"] and "display_text" not in plain["changes"] + assert plain["changes"]["final_url"] == "the ad's own final URL" + assert not [c for c in api.calls if c["path"] in ("Media", "AdExtensions")] + + def test_apply_uploads_media_then_creates_then_links(self, api, config, tmp_path, web): + import base64 + + png, jpeg = _png(1200, 628), _jpeg(1406, 736) + web["https://cdn.example.com/team.jpg"] = jpeg + preview = manage.draft_microsoft_image_extension( + config, ad_group_id="11", image_paths=[_file(tmp_path, "van.png", png)], + image_urls=["https://cdn.example.com/team.jpg"], alt_text="Plumber clearing a drain", + display_text="Same-day drain service", final_url="https://example.com/drain") + result = _apply(config, preview) + writes = [c["path"] for c in api.writes()] + assert writes == ["Media", "AdExtensions", "AdExtensionsAssociations/Set"] + media = _last(api, "Media", "POST")["body"] + assert media["AccountId"] == ACCOUNT + assert [(m["Type"], m["MediaType"]) for m in media["Media"]] == [("Image", "GenericImage")] * 2 + assert [base64.b64decode(m["Data"]) for m in media["Media"]] == [png, jpeg] + assert result["media_ids"] == [str(i) for i in sorted(int(i) for i in api.media)] + created = _last(api, "AdExtensions")["body"]["AdExtensions"] + first_media = int(result["media_ids"][0]) + assert created[0] == { + "Type": "ImageAdExtension", "AlternativeText": "Plumber clearing a drain", + "Description": preview["changes"]["image_payloads"][0]["name"][:100], + "ImageMediaIds": [first_media], + "Images": [{"Asset": {"Type": "ImageAsset", "Id": first_media, "SubType": "LandscapeImageMedia"}}], + "Layouts": ["SearchSingle", "SearchMultiple"], "DisplayText": "Same-day drain service", + "FinalUrls": ["https://example.com/drain"]} + assert created[1]["ImageMediaIds"] == [int(result["media_ids"][1])] + link = _last(api, "AdExtensionsAssociations/Set")["body"] + assert link["AssociationType"] == "AdGroup" + assert link["AdExtensionIdToEntityIdAssociations"] == [ + {"AdExtensionId": int(i), "EntityId": 11} for i in result["extension_ids"]] + assert result["linked_to"].startswith("ad group 'Drains'") + # The new extensions now show up on the ad group. + rows = [r for r in manage.get_microsoft_ad_extensions(config)["extensions"] if r["type"] == "Image"] + assert sorted(r["extension_id"] for r in rows) == sorted(result["extension_ids"]) + # Account and campaign scope link to those entities. + account = manage.draft_microsoft_image_extension(config, scope="account", alt_text="Van", + image_paths=[_file(tmp_path, "acct.png", _png(1300, 681))]) + _apply(config, account) + assert _last(api, "AdExtensionsAssociations/Set")["body"]["AssociationType"] == "Account" + assert _last(api, "AdExtensionsAssociations/Set")["body"]["AdExtensionIdToEntityIdAssociations"][0]["EntityId"] == int(ACCOUNT) + assert "FinalUrls" not in _last(api, "AdExtensions")["body"]["AdExtensions"][0] + campaign = manage.draft_microsoft_image_extension(config, campaign_id="600", alt_text="Van", + image_paths=[_file(tmp_path, "brand.png", _png(1400, 733))]) + _apply(config, campaign) + assert _last(api, "AdExtensionsAssociations/Set")["body"]["AssociationType"] == "Campaign" + + @pytest.mark.parametrize("failing,created_keys", [ + ("AdExtensions", {"media_ids", "done"}), + ("AdExtensionsAssociations/Set", {"media_ids", "extension_ids", "done"}), + ]) + def test_a_later_step_failing_reports_what_exists(self, api, config, tmp_path, failing, created_keys): + preview = manage.draft_microsoft_image_extension(config, campaign_id=CAMPAIGN, alt_text="Van", + image_paths=[_file(tmp_path, "van.png", _png(1200, 628))]) + api.fail[("POST", failing)] = MicrosoftAdsApiError("CampaignServiceImageAdExtensionPilotNotEnabledForCustomer", + status=400, codes=["CampaignServiceImageAdExtensionPilotNotEnabledForCustomer"]) + result = ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=False) + again = ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=False) + assert result["status"] == "PARTIAL_APPLY", result + assert set(result["created"]) == created_keys + assert result["created"]["media_ids"] == list(api.media) + if "extension_ids" in created_keys: + assert result["created"]["extension_ids"][0] in api.extensions + assert "PilotNotEnabled" in result["error"] and "uploaded 1 image(s)" in result["error"] + assert "No pending plan" in _text(again) + assert len(api.media) == 1 + + def test_a_refused_upload_changes_nothing_and_keeps_the_plan(self, api, config, tmp_path): + preview = manage.draft_microsoft_image_extension(config, campaign_id=CAMPAIGN, alt_text="Van", + image_paths=[_file(tmp_path, "van.png", _png(1200, 628))]) + api.fail[("POST", "Media")] = MicrosoftAdsApiError("CampaignServiceImageOverweight", status=400, + codes=["CampaignServiceImageOverweight"]) + result = ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=False) + assert result.get("status") != "PARTIAL_APPLY" and "ImageOverweight" in _text(result), result + assert not [c for c in api.calls if c["path"] == "AdExtensions"] and not api.media + # Nothing was created, so the plan stays pending and can be applied once the cause is fixed. + del api.fail[("POST", "Media")] + assert ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=False)["status"] == "APPLIED" + + def test_dry_run_rechecks_every_image(self, api, config, tmp_path, web): + web["https://cdn.example.com/team.jpg"] = _jpeg(1406, 736) + from_url = manage.draft_microsoft_image_extension(config, campaign_id=CAMPAIGN, alt_text="Team", + image_urls=["https://cdn.example.com/team.jpg"]) + web["https://cdn.example.com/team.jpg"] = _jpeg(1200, 628) # replaced on the server + dry = ads_write.confirm_and_apply(config, plan_id=from_url["plan_id"], dry_run=True) + assert dry["status"] != "DRY_RUN_SUCCESS" and "changed since the preview" in _text(dry) + path = _file(tmp_path, "van.png", _png(1200, 628)) + from_file = manage.draft_microsoft_image_extension(config, campaign_id=CAMPAIGN, alt_text="Van", image_paths=[path]) + dry = ads_write.confirm_and_apply(config, plan_id=from_file["plan_id"], dry_run=True) + assert dry["status"] == "DRY_RUN_SUCCESS" and dry["checks"]["images_verified"] == 1, dry + (tmp_path / "van.png").write_bytes(_png(1200, 628, pad=10)) + assert "changed since the preview" in _text(ads_write.confirm_and_apply(config, plan_id=from_file["plan_id"], dry_run=False)) + assert not api.media and not [c for c in api.calls if c["path"] == "Media"] + + def test_link_limits(self, api, config, tmp_path): + image = _file(tmp_path, "van.png", _png(1200, 628)) + for n in range(6): + self._image_link(api, str(7100 + n), "600", "Campaign") + warned = manage.draft_microsoft_image_extension(config, campaign_id="600", alt_text="Van", image_paths=[image]) + assert any("would have 7 image extensions" in w for w in warned["warnings"]) + for n in range(6, 25): + self._image_link(api, str(7100 + n), "600", "Campaign") + refused = manage.draft_microsoft_image_extension(config, campaign_id="600", alt_text="Van", image_paths=[image]) + assert "has 25 image extension(s)" in _text(refused) and "over Microsoft's 25" in _text(refused) + # Links added after the draft are caught by the dry run. + api.ext_links = [l for l in api.ext_links if l[1] != "600"] + preview = manage.draft_microsoft_image_extension(config, campaign_id="600", alt_text="Van", image_paths=[image]) + for n in range(25): + self._image_link(api, str(7200 + n), "600", "Campaign") + assert "now has 25" in _text(ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=True)) + + def test_read_lists_image_extensions_at_every_level(self, api, config): + assert any("No image extensions are linked" in i for i in manage.get_microsoft_ad_extensions(config)["insights"]) + self._image_link(api, "7003", "11", "AdGroup") + self._image_link(api, "7004", ACCOUNT, "Account", alt="Our team") + before = len(api.calls) + result = manage.get_microsoft_ad_extensions(config) + rows = {r["extension_id"]: r for r in result["extensions"]} + group = rows["7003"] + assert group["type"] == "Image" and group["level"] == "ad_group" and group["entity"] == "Drains" + assert group["campaign"] == "Acme Plumbing - Search" and group["media_ids"] == ["7103"] + assert group["alt_text"] == "Technician at a drain" and group["layouts"] == ["SearchSingle"] + assert group["remove_id"] == "7003~11~AdGroup" + assert rows["7004"]["level"] == "account" and rows["7004"]["remove_id"] == f"7004~{ACCOUNT}~Account" + assert rows["7001"]["level"] == "campaign" # the sitelink is still there + assert not any("No image extensions" in i for i in result["insights"]) + # Ad groups are asked for together, not one request each. + group_queries = [c for c in api.calls[before:] if c["path"] == "AdExtensionsAssociations/Query" + and c["body"]["AssociationType"] == "AdGroup"] + assert len(group_queries) == 1 and sorted(group_queries[0]["body"]["EntityIds"]) == [11, 12, 21] + assert "ImageAdExtension" in group_queries[0]["body"]["AdExtensionType"] + + def test_read_shows_which_picture_each_image_extension_holds(self, api, config, tmp_path): + # The association query leaves the images out (as Microsoft does live), so + # the read asks for them by id and then looks up each picture. + preview = manage.draft_microsoft_image_extension( + config, campaign_id=CAMPAIGN, alt_text="Technician at a drain", display_text="Drain cleaning", + image_paths=[_file(tmp_path, f"d{i}.png", _png(1200, 628, pad=i)) for i in range(3)]) + result = _apply(config, preview) + before = len(api.calls) + rows = {r["extension_id"]: r for r in manage.get_microsoft_ad_extensions(config, campaign_id=CAMPAIGN)["extensions"] + if r["type"] == "Image"} + assert sorted(rows) == sorted(result["extension_ids"]) + for ext_id, media_id in zip(result["extension_ids"], result["media_ids"], strict=True): + row = rows[ext_id] + assert row["media_ids"] == [media_id] + assert row["display_text"] == "Drain cleaning" and row["layouts"] == ["SearchSingle", "SearchMultiple"] + assert row["images"] == [{"media_id": media_id, "media_type": "GenericImage", "width": 1200, "height": 628, + "url": f"https://www.bing.com/th?id=OADD2.{media_id}"}] + by_id = [c for c in api.calls[before:] if c["path"] == "AdExtensions/QueryByIds"] + assert len(by_id) == 1 and by_id[0]["body"]["ReturnAdditionalFields"] == "Images,DisplayText,Layouts" + assert sorted(map(str, by_id[0]["body"]["AdExtensionIds"])) == sorted(result["extension_ids"]) + media = [c for c in api.calls[before:] if c["path"] == "MediaMetaData/QueryByIds"] + assert len(media) == 1 and sorted(map(str, media[0]["body"]["MediaIds"])) == sorted(result["media_ids"]) + + def test_read_keeps_the_rows_when_image_details_fail(self, api, config): + self._image_link(api, "7003", "11", "AdGroup") + api.fail[("POST", "MediaMetaData/QueryByIds")] = MicrosoftAdsApiError("Internal error", status=500) + result = manage.get_microsoft_ad_extensions(config) + row = next(r for r in result["extensions"] if r["extension_id"] == "7003") + assert row["remove_id"] == "7003~11~AdGroup" and "images" not in row + assert any("Image details could not be read" in i for i in result["insights"]) + + def test_large_images_get_no_size_warning(self, api, config, tmp_path): + # Microsoft's Image reference names a 75 KB cap that it does not enforce: + # 125-300 KB JPEGs uploaded on a live account. Only 5 MB is a limit. + big = _file(tmp_path, "big.png", _png(1200, 628, pad=300_000)) + preview = manage.draft_microsoft_image_extension(config, campaign_id=CAMPAIGN, alt_text="Van", image_paths=[big]) + assert "plan_id" in preview + assert not [w for w in preview["warnings"] if "KB" in w or "base64" in w] + + def test_unlinking_an_image_extension(self, api, config): + self._image_link(api, "7003", "11", "AdGroup") + preview = manage.remove_microsoft_entity(config, entity_type="extension_association", entity_id="7003~11~AdGroup") + assert any("unlinks the extension only" in w for w in preview["warnings"]) + _apply(config, preview) + assert _last(api, "AdExtensionsAssociations", "DELETE")["body"] == { + "AccountId": ACCOUNT, "AssociationType": "AdGroup", + "AdExtensionIdToEntityIdAssociations": [{"AdExtensionId": 7003, "EntityId": 11}]} + assert ("7003", "11", "AdGroup") not in api.ext_links and "7003" in api.extensions + bad = manage.remove_microsoft_entity(config, entity_type="extension_association", entity_id="7003~11~Keyword") + assert "Account|Campaign|AdGroup" in _text(bad) + + def test_server_tool_and_hosted_paths(self, api, config, tmp_path, monkeypatch): + from adloop import runtime, server + + runtime.set_default_config(config) + try: + preview = server.draft_microsoft_image_extension( + ad_group_id="11", alt_text="Van", image_paths=[_file(tmp_path, "van.png", _png(1200, 628))]) + assert preview["status"] == "PENDING_CONFIRMATION" and preview["platform"] == "microsoft" + monkeypatch.setattr("adloop.runtime.deployment_mode", lambda: "server") + hosted = server.draft_microsoft_image_extension(ad_group_id="11", alt_text="Van", image_paths=["/etc/hosts"]) + assert "hosted server" in hosted["error"] + finally: + runtime.set_default_config(None) + + def test_uploaded_images_are_used_by_id(self, api, config, tmp_path): + import base64 + + from adloop import uploads + + uploads.set_upload_store(uploads.LocalUploadStore(tmp_path / "uploads")) + try: + data = _png(1200, 628) + upload = uploads.get_upload_store().put(uploads.current_tenant(), "crew.png", data) + preview = manage.draft_microsoft_image_extension(config, campaign_id=CAMPAIGN, alt_text="Our crew", + upload_ids=[upload.upload_id]) + assert preview["changes"]["images"] == [f"upload {upload.upload_id}: PNG 1200x628 (1.91:1), 0.1 KB"] + _apply(config, preview) + assert base64.b64decode(_last(api, "Media", "POST")["body"]["Media"][0]["Data"]) == data + missing = manage.draft_microsoft_image_extension(config, campaign_id=CAMPAIGN, alt_text="Our crew", + upload_ids=["up_missing0000"]) + assert "Upload 1: upload up_missing0000 was not found" in _text(missing) and "plan_id" not in missing + finally: + uploads.set_upload_store(None) diff --git a/tests/test_oauth_redirect.py b/tests/test_oauth_redirect.py new file mode 100644 index 00000000..6043e8b8 --- /dev/null +++ b/tests/test_oauth_redirect.py @@ -0,0 +1,94 @@ +"""The one-shot localhost listener for sign-in redirects (oauth_redirect). + +A connection that trickles its request must not hold the sign-in past its +deadline, nor keep a real redirect waiting behind it until then. +""" + +from __future__ import annotations + +import socket +import threading +import time + +import pytest + +from adloop import oauth_redirect +from adloop.oauth_redirect import RedirectTimeout, listen_once + + +def _free_port() -> int: + with socket.socket() as s: + s.bind(("127.0.0.1", 0)) + return s.getsockname()[1] + + +def _connect(port: int) -> socket.socket: + for _ in range(100): + try: + return socket.create_connection(("127.0.0.1", port), timeout=2) + except OSError: + time.sleep(0.02) + raise AssertionError("listener did not come up") + + +def _trickle(port: int, data: bytes, every: float, stop: threading.Event) -> None: + try: + sock = _connect(port) + except AssertionError: + return + try: + for byte in data: + if stop.is_set(): + break + sock.sendall(bytes([byte])) + time.sleep(every) + except OSError: + pass # the listener cut the connection off + finally: + sock.close() + + +def _run(uri: str, timeout: float) -> tuple[dict | Exception, float]: + started = time.monotonic() + try: + result: dict | Exception = listen_once(uri, timeout, provider="Test") + except RedirectTimeout as exc: + result = exc + return result, time.monotonic() - started + + +@pytest.mark.parametrize("data", [ + b"GET /callback?code=c1&state=s1 HTTP/1.1\r\n", # a slow request line + b"GET /callback HTTP/1.1\r\nHost: x\r\nX-Slow: " + b"a" * 40, # slow headers +]) +def test_a_trickled_request_cannot_outlast_the_deadline(data): + port = _free_port() + stop = threading.Event() + worker = threading.Thread(target=_trickle, args=(port, data, 0.05, stop), daemon=True) + worker.start() + result, elapsed = _run(f"http://127.0.0.1:{port}/callback", 0.4) + stop.set() + assert isinstance(result, RedirectTimeout) + assert elapsed < 1.2, f"the listener stayed {elapsed:.2f}s past a 0.4s deadline" + + +def test_a_real_redirect_behind_a_trickling_connection_is_served(monkeypatch): + monkeypatch.setattr(oauth_redirect, "_PER_CONNECTION_SECONDS", 0.3) + port = _free_port() + stop = threading.Event() + slow = threading.Thread(target=_trickle, args=(port, b"GET /callback HTTP/1.1\r\n" * 10, 0.05, stop), + daemon=True) + slow.start() + + def real(): + time.sleep(0.1) + sock = _connect(port) + sock.sendall(b"GET /callback?code=c1&state=s1 HTTP/1.1\r\nHost: localhost\r\n\r\n") + sock.recv(1024) + sock.close() + + threading.Thread(target=real, daemon=True).start() + result, elapsed = _run(f"http://127.0.0.1:{port}/callback", 5.0) + stop.set() + assert result == {"code": "c1", "state": "s1"} + assert elapsed < 2.0 diff --git a/tests/test_server.py b/tests/test_server.py index 01c5e75f..0d68fbde 100644 --- a/tests/test_server.py +++ b/tests/test_server.py @@ -389,6 +389,7 @@ def test_toolset_slugs_match_the_cross_repo_contract(self): assert list(TOOLSETS) == [ "ads", "ga4", "tracking", "gtm", "gsc", "web", "merchant", "reddit", + "microsoft_ads", ] @pytest.mark.asyncio From 4651a2ca42a14e2d8f35b6e47213cf33a20fe172 Mon Sep 17 00:00:00 2001 From: Illia Sapryga Date: Sun, 8 Nov 2026 16:33:34 -0600 Subject: [PATCH 4/6] Microsoft Advertising: review fixes - Broad match only with conversion-based bidding (MaxConversions, MaxConversionValue, TargetCpa, TargetRoas); Maximize Clicks no longer counts. Moving to any other strategy is refused while active broad keywords exist, at the draft and again at the dry run and apply; the keyword read's insight follows the same rule. - remove_microsoft_entity reads a campaign criterion at the draft, names its type and target, and refuses removing the last targeted location (the campaign would serve everywhere), again at the dry run. - Request bodies, snapshots and ids move from plan.changes to ChangePlan.apply_only_payload; preflight and apply read plan.apply_payload(). Drafts use the shared store_draft and blocked_operation_error. - MaxConversions without an active conversion goal is refused at the draft and the dry run (Microsoft refused such a create live with ConversionGoalCriteriaNotMetForBiddingScheme) and names the alternatives. - Throttling: codes 117 and 207 (and HTTP 429) raise at once with retry_after 60 instead of retrying after 5 s. - Plans store their campaign and ad group, so dry runs and applies read three lists instead of every ad group of the account; campaign reads ask once per campaign for its targeting (CriterionType Targets, with the per-type queries as fallback). - Reads: criterion type Radius, Audience Network inherited from the campaign when an ad group has no adjustment of its own; new campaigns warn about the Audience Network default. - Sign-in binds a free localhost port (Entra ignores the port), keeps listening until the state matches, and writes the token through an O_EXCL temp file. A bare 105 after a working sign-in is explained: the identity is not a user of the account, often because its users sign in with Google, which is not supported yet. - languages=['All'] is refused; target_cpa and max_cpc on a strategy that cannot use them are refused instead of dropped. - Dead code removed; the schedule limit is 7 windows a day throughout. --- .claude/rules/adloop.md | 7 +- .cursor/rules/adloop.mdc | 7 +- README.md | 6 +- config.yaml.example | 10 +- src/adloop/microsoft_ads/auth.py | 68 +++-- src/adloop/microsoft_ads/client.py | 51 +++- src/adloop/microsoft_ads/manage.py | 432 ++++++++++++++++++++--------- src/adloop/microsoft_ads/read.py | 87 ++++-- src/adloop/microsoft_ads/write.py | 114 ++++---- src/adloop/oauth_redirect.py | 158 ++++++----- src/adloop/rules/adloop.md | 7 +- src/adloop/server.py | 40 ++- tests/test_microsoft_ads.py | 128 +++++++-- tests/test_microsoft_ads_manage.py | 304 ++++++++++++++++---- tests/test_oauth_redirect.py | 30 ++ 15 files changed, 1043 insertions(+), 406 deletions(-) diff --git a/.claude/rules/adloop.md b/.claude/rules/adloop.md index 3f0adc6b..a1ad6274 100644 --- a/.claude/rules/adloop.md +++ b/.claude/rules/adloop.md @@ -267,7 +267,7 @@ Reddit is a second ad platform with its own connection (own OAuth app, no develo ### Microsoft Advertising Tools -Microsoft Advertising (Bing, Yahoo, AOL, DuckDuckGo search ads) through the REST API v13. Toolset `microsoft_ads`; needs `microsoft_ads.developer_token`, `microsoft_ads.client_id` (an Entra app with public client flows and the msads.manage permission) and a one-time `adloop microsoft-login` (browser sign-in on `http://localhost:8080/callback`; sign in with the user that has access to the ad accounts. Directories with security defaults block the device-code flow with sign-in error 530035, so `--device-code` is only a fallback). `customer_id` is the manager account, `ad_account_id` the default ad account; `list_microsoft_ads_accounts` shows both. +Microsoft Advertising (Bing, Yahoo, AOL, DuckDuckGo search ads) through the REST API v13. Toolset `microsoft_ads`; needs `microsoft_ads.developer_token`, `microsoft_ads.client_id` (an Entra app with public client flows and the msads.manage permission) and a one-time `adloop microsoft-login` (browser sign-in; the Entra app registers `http://localhost/callback` and the sign-in listens on a free port of it, since Entra ignores the port of localhost redirects. Sign in with the user that has access to the ad accounts. Directories with security defaults block the device-code flow with sign-in error 530035, so `--device-code` is only a fallback). Users who sign in to Microsoft Advertising with Google are not supported yet: an `MICROSOFT_ADS_NOT_AN_ACCOUNT_USER` error after a working sign-in means the Microsoft identity is not a user of the ad account; invite a Microsoft account or work (Entra) user and sign in as that user. `customer_id` is the manager account, `ad_account_id` the default ad account; `list_microsoft_ads_accounts` shows both. | Tool | When to Use | Key Parameters | |------|-------------|----------------| @@ -302,10 +302,13 @@ Microsoft Advertising (Bing, Yahoo, AOL, DuckDuckGo search ads) through the REST - **Location intent matters for local businesses.** `PeopleInOrSearchingForOrViewingPages` (Microsoft's default) also reaches people elsewhere searching about the area. `get_microsoft_location_performance` shows how much spend that "location of interest" traffic took. - **Monthly spend:** Microsoft may spend up to 30.4 × the daily budget in a month; the budget preview says so. - **Writes** go through draft → preview → `confirm_and_apply`. Microsoft has no validate-only mode: the dry run re-reads the target, refuses if the budget or status changed since the draft or the campaign moved to a shared budget, and re-checks the cap. The real apply runs the same checks again right before sending, so a change made in Microsoft Advertising in between is refused, not overwritten: draft again. Updates send only the changed field. -- **Management rules** mirror Google Ads: broad match is refused on ManualCpc / EnhancedCpc campaigns, moving to manual bidding is refused while active broad keywords exist, new campaigns need languages and locations (default PeopleIn), new RSAs and campaigns are paused, while new keywords and ad groups are created Active as in Google Ads (the preview's `status_on_create` says so, and keywords in a live ad group serve as soon as they are applied), keyword and ad group bid raises are capped by `max_bid_increase_pct` (including a keyword falling back to the ad group bid), a first ad schedule needs a double confirmation. Replacing a schedule window deletes the old window before adding the new one when they overlap; the preview warns when that leaves the campaign briefly unscheduled. Negative keywords go in shared lists by default; every negative draft names active keywords it would block. +- **Management rules** mirror Google Ads: broad match is refused unless the campaign uses conversion-based bidding (MaxConversions, MaxConversionValue, or a target CPA/ROAS; Maximize Clicks does not count), moving to any other strategy is refused while active broad keywords exist, MaxConversions is refused (at the draft and the dry run) while the account has no active conversion goal, because Microsoft refuses it then, new campaigns need languages (not `All`) and locations (default PeopleIn), new RSAs and campaigns are paused, while new keywords and ad groups are created Active as in Google Ads (the preview's `status_on_create` says so, and keywords in a live ad group serve as soon as they are applied), keyword and ad group bid raises are capped by `max_bid_increase_pct` (including a keyword falling back to the ad group bid), a first ad schedule needs a double confirmation. Replacing a schedule window deletes the old window before adding the new one when they overlap; the preview warns when that leaves the campaign briefly unscheduled. Negative keywords go in shared lists by default; every negative draft names active keywords it would block. - **Multi-step applies** (a campaign then its targeting, a list then its attachments, extensions then their links) end with `PARTIAL_APPLY` when a later step fails, or when Microsoft creates some items of a batch and refuses others: `created` lists the IDs that exist, and the plan is retired so nothing is created twice. Check the account, then draft only what is missing. - **Image extensions** (`draft_microsoft_image_extension`): JPEG, PNG or non-animated GIF, at most 5 MB, **1.91:1** (e.g. 1200x628), at least 703x368, at most 2592 wide and 2048 high; the draft refuses anything else and says how to crop it. Ask the user for alt text that describes the photo. Microsoft's help allows 25 image extensions per account, campaign or ad group, its API reference says 6: the draft warns above 6 and refuses above 25. `display_text` adds the multi-image layout, which needs at least five images in four extensions. **Caution:** image extensions can take search ads beyond Bing results: Microsoft's audience ads guide says search ads are extended to native placements on the Microsoft Audience Network (Outlook, MSN) with their image extensions, so check the ad groups' Audience Network setting with `get_microsoft_ad_groups` when the client wants search only. Images without a public URL go through `upload_images` first. - Reports are built asynchronously and take a few seconds; long date ranges at keyword or search-term level take longer. +- **Rate limits:** Microsoft counts calls per customer in a sliding 60-second window (code 117) and caps concurrent reports (code 207). Both come back as `MICROSOFT_ADS_RATE_LIMITED` with `retry_after` 60: wait that long, never retry in a loop. +- **Removing a criterion** (`remove_microsoft_entity`, `campaign_criterion`) reads it first and names it; the last targeted location is refused, because the campaign would serve everywhere. Replace locations with `update_microsoft_campaign_targeting` instead. +- **Audience Network:** an ad group without its own `audience_ads_bid_adjustment` inherits the campaign's; -100 switches it off. `get_microsoft_ad_groups` shows the effective setting and where it is set (`audience_network`). - Search terms with clicks and no conversions are candidates, not verdicts: calls from Microsoft ads convert outside its view unless call tracking feeds back. - **Conversions** come from Microsoft's `ConversionsQualified` columns (the old `Conversions` columns are deprecated and read 0 in keyword and search-term reports); conversion rate and CPA are computed from them. A UET tag is required only by URL, duration, pages-per-visit and event goals: offline-import goals need none, and an unverified tag that no active goal uses is a loose end (warn), not a broken setup. diff --git a/.cursor/rules/adloop.mdc b/.cursor/rules/adloop.mdc index 5246170f..0c48f284 100644 --- a/.cursor/rules/adloop.mdc +++ b/.cursor/rules/adloop.mdc @@ -269,7 +269,7 @@ Reddit is a second ad platform with its own connection (own OAuth app, no develo ### Microsoft Advertising Tools -Microsoft Advertising (Bing, Yahoo, AOL, DuckDuckGo search ads) through the REST API v13. Toolset `microsoft_ads`; needs `microsoft_ads.developer_token`, `microsoft_ads.client_id` (an Entra app with public client flows and the msads.manage permission) and a one-time `adloop microsoft-login` (browser sign-in on `http://localhost:8080/callback`; sign in with the user that has access to the ad accounts. Directories with security defaults block the device-code flow with sign-in error 530035, so `--device-code` is only a fallback). `customer_id` is the manager account, `ad_account_id` the default ad account; `list_microsoft_ads_accounts` shows both. +Microsoft Advertising (Bing, Yahoo, AOL, DuckDuckGo search ads) through the REST API v13. Toolset `microsoft_ads`; needs `microsoft_ads.developer_token`, `microsoft_ads.client_id` (an Entra app with public client flows and the msads.manage permission) and a one-time `adloop microsoft-login` (browser sign-in; the Entra app registers `http://localhost/callback` and the sign-in listens on a free port of it, since Entra ignores the port of localhost redirects. Sign in with the user that has access to the ad accounts. Directories with security defaults block the device-code flow with sign-in error 530035, so `--device-code` is only a fallback). Users who sign in to Microsoft Advertising with Google are not supported yet: an `MICROSOFT_ADS_NOT_AN_ACCOUNT_USER` error after a working sign-in means the Microsoft identity is not a user of the ad account; invite a Microsoft account or work (Entra) user and sign in as that user. `customer_id` is the manager account, `ad_account_id` the default ad account; `list_microsoft_ads_accounts` shows both. | Tool | When to Use | Key Parameters | |------|-------------|----------------| @@ -304,10 +304,13 @@ Microsoft Advertising (Bing, Yahoo, AOL, DuckDuckGo search ads) through the REST - **Location intent matters for local businesses.** `PeopleInOrSearchingForOrViewingPages` (Microsoft's default) also reaches people elsewhere searching about the area. `get_microsoft_location_performance` shows how much spend that "location of interest" traffic took. - **Monthly spend:** Microsoft may spend up to 30.4 × the daily budget in a month; the budget preview says so. - **Writes** go through draft → preview → `confirm_and_apply`. Microsoft has no validate-only mode: the dry run re-reads the target, refuses if the budget or status changed since the draft or the campaign moved to a shared budget, and re-checks the cap. The real apply runs the same checks again right before sending, so a change made in Microsoft Advertising in between is refused, not overwritten: draft again. Updates send only the changed field. -- **Management rules** mirror Google Ads: broad match is refused on ManualCpc / EnhancedCpc campaigns, moving to manual bidding is refused while active broad keywords exist, new campaigns need languages and locations (default PeopleIn), new RSAs and campaigns are paused, while new keywords and ad groups are created Active as in Google Ads (the preview's `status_on_create` says so, and keywords in a live ad group serve as soon as they are applied), keyword and ad group bid raises are capped by `max_bid_increase_pct` (including a keyword falling back to the ad group bid), a first ad schedule needs a double confirmation. Replacing a schedule window deletes the old window before adding the new one when they overlap; the preview warns when that leaves the campaign briefly unscheduled. Negative keywords go in shared lists by default; every negative draft names active keywords it would block. +- **Management rules** mirror Google Ads: broad match is refused unless the campaign uses conversion-based bidding (MaxConversions, MaxConversionValue, or a target CPA/ROAS; Maximize Clicks does not count), moving to any other strategy is refused while active broad keywords exist, MaxConversions is refused (at the draft and the dry run) while the account has no active conversion goal, because Microsoft refuses it then, new campaigns need languages (not `All`) and locations (default PeopleIn), new RSAs and campaigns are paused, while new keywords and ad groups are created Active as in Google Ads (the preview's `status_on_create` says so, and keywords in a live ad group serve as soon as they are applied), keyword and ad group bid raises are capped by `max_bid_increase_pct` (including a keyword falling back to the ad group bid), a first ad schedule needs a double confirmation. Replacing a schedule window deletes the old window before adding the new one when they overlap; the preview warns when that leaves the campaign briefly unscheduled. Negative keywords go in shared lists by default; every negative draft names active keywords it would block. - **Multi-step applies** (a campaign then its targeting, a list then its attachments, extensions then their links) end with `PARTIAL_APPLY` when a later step fails, or when Microsoft creates some items of a batch and refuses others: `created` lists the IDs that exist, and the plan is retired so nothing is created twice. Check the account, then draft only what is missing. - **Image extensions** (`draft_microsoft_image_extension`): JPEG, PNG or non-animated GIF, at most 5 MB, **1.91:1** (e.g. 1200x628), at least 703x368, at most 2592 wide and 2048 high; the draft refuses anything else and says how to crop it. Ask the user for alt text that describes the photo. Microsoft's help allows 25 image extensions per account, campaign or ad group, its API reference says 6: the draft warns above 6 and refuses above 25. `display_text` adds the multi-image layout, which needs at least five images in four extensions. **Caution:** image extensions can take search ads beyond Bing results: Microsoft's audience ads guide says search ads are extended to native placements on the Microsoft Audience Network (Outlook, MSN) with their image extensions, so check the ad groups' Audience Network setting with `get_microsoft_ad_groups` when the client wants search only. Images without a public URL go through `upload_images` first. - Reports are built asynchronously and take a few seconds; long date ranges at keyword or search-term level take longer. +- **Rate limits:** Microsoft counts calls per customer in a sliding 60-second window (code 117) and caps concurrent reports (code 207). Both come back as `MICROSOFT_ADS_RATE_LIMITED` with `retry_after` 60: wait that long, never retry in a loop. +- **Removing a criterion** (`remove_microsoft_entity`, `campaign_criterion`) reads it first and names it; the last targeted location is refused, because the campaign would serve everywhere. Replace locations with `update_microsoft_campaign_targeting` instead. +- **Audience Network:** an ad group without its own `audience_ads_bid_adjustment` inherits the campaign's; -100 switches it off. `get_microsoft_ad_groups` shows the effective setting and where it is set (`audience_network`). - Search terms with clicks and no conversions are candidates, not verdicts: calls from Microsoft ads convert outside its view unless call tracking feeds back. - **Conversions** come from Microsoft's `ConversionsQualified` columns (the old `Conversions` columns are deprecated and read 0 in keyword and search-term reports); conversion rate and CPA are computed from them. A UET tag is required only by URL, duration, pages-per-visit and event goals: offline-import goals need none, and an unverified tag that no active goal uses is a loose end (warn), not a broken setup. diff --git a/README.md b/README.md index 28e148b5..4b762a3c 100644 --- a/README.md +++ b/README.md @@ -268,9 +268,9 @@ Microsoft Advertising (Bing, Yahoo, AOL and DuckDuckGo search ads) through the R | `draft_microsoft_responsive_search_ad` / `update_microsoft_responsive_search_ad` | New RSAs (created **paused**) and copy, URL and path changes | | `draft_microsoft_sitelinks` / `draft_microsoft_callouts` / `draft_microsoft_structured_snippet` / `draft_microsoft_call_extension` | Create extensions and link them to a campaign or the account | -The same management rules as Google Ads apply: broad match is refused on manual bidding (at the draft and again at apply), moving to manual bidding is refused while active broad keywords exist, and a campaign's first ad schedule needs a double confirmation. +The same management rules as Google Ads apply: broad match is refused unless the campaign uses conversion-based bidding (at the draft and again at apply; Maximize Clicks does not count), moving to any other strategy is refused while active broad keywords exist, and a campaign's first ad schedule needs a double confirmation. MaxConversions is refused while the account has no active conversion goal, because Microsoft refuses such a campaign. -> **Setup for Microsoft Advertising tools** — You need a developer token (Microsoft Advertising → **Settings → Developer settings**, or [developers.ads.microsoft.com](https://developers.ads.microsoft.com/Account)) and an app registration in Microsoft Entra ID: allow public client flows, add the delegated `msads.manage` permission of Microsoft Advertising, and add `http://localhost:8080/callback` as a mobile and desktop redirect URI. Put the token and the app's client id under `microsoft_ads` in `~/.adloop/config.yaml`, then run `adloop microsoft-login` and sign in with the user that has access to the ad accounts. It stores the refresh token at `~/.adloop/microsoft_token.json`. Directories with security defaults block the device-code flow (sign-in error 530035), so `adloop microsoft-login --device-code` is only a fallback. Microsoft has no validate-only mode, so `confirm_and_apply(dry_run=true)` re-reads the target, refuses one that changed since the draft and re-checks the caps; the real apply runs the same checks again first. +> **Setup for Microsoft Advertising tools** — You need a developer token (Microsoft Advertising → **Settings → Developer settings**, or [developers.ads.microsoft.com](https://developers.ads.microsoft.com/Account)) and an app registration in Microsoft Entra ID: allow public client flows, add the delegated `msads.manage` permission of Microsoft Advertising, and add `http://localhost/callback` as a mobile and desktop redirect URI (the sign-in listens on a free port; Entra ignores the port of localhost redirects). Put the token and the app's client id under `microsoft_ads` in `~/.adloop/config.yaml`, then run `adloop microsoft-login` and sign in with the user that has access to the ad accounts. It stores the refresh token at `~/.adloop/microsoft_token.json`. Directories with security defaults block the device-code flow (sign-in error 530035), so `adloop microsoft-login --device-code` is only a fallback. Signing in with a Google identity is not supported yet: if the account's users sign in to Microsoft Advertising with Google, invite a Microsoft account or work (Entra) user to the ad account and sign in as that user. Microsoft has no validate-only mode, so `confirm_and_apply(dry_run=true)` re-reads the target, refuses one that changed since the draft and re-checks the caps; the real apply runs the same checks again first. ### Image Uploads @@ -648,7 +648,7 @@ src/adloop/ │ ├── read.py # Accounts, campaigns, ad groups, keywords, ads, reports, search terms, conversion audit │ ├── manage.py # Drafts, preflight and apply for campaigns, targeting, keywords, negatives, ads, extensions │ └── write.py # Budget and status drafts; routes every microsoft_ plan to its preflight and apply -├── oauth_redirect.py # One-shot localhost listener for sign-in redirects +├── oauth_redirect.py # Localhost listener for sign-in redirects (free port, waits for its state) └── safety/ ├── guards.py # Budget caps, bid limits, blocked operations, Broad Match safety ├── preview.py # Change plans and previews diff --git a/config.yaml.example b/config.yaml.example index c95d1097..d86b1fbe 100644 --- a/config.yaml.example +++ b/config.yaml.example @@ -104,9 +104,13 @@ microsoft_ads: # Microsoft Advertising API permission msads.manage. Its application id: # 3. `adloop microsoft-login` once: the browser opens, sign in with the # account that has access to the ad accounts; the refresh token lands in - # token_path. The app needs http://localhost:8080/callback as a - # mobile/desktop redirect URI. (--device-code is a fallback; directories - # with security defaults block it with error 530035.) + # token_path. The app needs http://localhost/callback as a + # mobile/desktop redirect URI (the sign-in listens on a free port; Entra + # ignores the port of localhost redirects). (--device-code is a fallback; + # directories with security defaults block it with error 530035.) + # Users who sign in to Microsoft Advertising with Google are not + # supported yet: invite a Microsoft account or work (Entra) user to the + # ad account and sign in as that user. developer_token: "" client_id: "" client_secret: "" # only for confidential (web) apps diff --git a/src/adloop/microsoft_ads/auth.py b/src/adloop/microsoft_ads/auth.py index c893f193..1d4dcc7e 100644 --- a/src/adloop/microsoft_ads/auth.py +++ b/src/adloop/microsoft_ads/auth.py @@ -7,8 +7,9 @@ here; a hosted deployment overrides :meth:`MicrosoftCredentials.persist`). ``adloop microsoft-login`` signs in once in the browser (authorization code -with PKCE; the redirect lands on ``http://localhost:8080/callback``, which -the Entra app must list as a mobile/desktop redirect URI) and stores the +with PKCE; the redirect lands on ``http://localhost:/callback``. +The Entra app lists ``http://localhost/callback`` as a mobile/desktop +redirect URI: Entra ignores the port of localhost redirects) and stores the refresh token in ``token_path``. Directories with security defaults block the device-code flow (sign-in error 530035), so it is only the fallback: ``adloop microsoft-login --device-code``. The Entra app must allow public @@ -31,7 +32,8 @@ _AUTHORITY = "https://login.microsoftonline.com/{tenant}/oauth2/v2.0" _EXPIRY_MARGIN_SECONDS = 120 _TIMEOUT_SECONDS = 30 -BROWSER_REDIRECT_URI = "http://localhost:8080/callback" +# What the Entra app registers; the sign-in itself uses a free port on it. +BROWSER_REDIRECT_URI = "http://localhost/callback" _BROWSER_LOGIN_TIMEOUT_SECONDS = 300 @@ -195,13 +197,23 @@ def persist(self, payload: dict) -> None: def write_token_file(path: Path, data: dict) -> None: - """Write the token file with owner-only permissions.""" + """Write the token file with owner-only permissions. + + The temporary file gets a fresh random name and is opened with O_EXCL, so + a file or symlink planted at that name is never written through. + """ + import secrets + path.parent.mkdir(parents=True, exist_ok=True) - tmp = path.with_suffix(path.suffix + ".tmp") - fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600) - with os.fdopen(fd, "w") as handle: - json.dump(data, handle) - os.replace(tmp, path) + tmp = path.with_name(f".{path.name}.{secrets.token_hex(8)}.tmp") + fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0), 0o600) + try: + with os.fdopen(fd, "w") as handle: + json.dump(data, handle) + os.replace(tmp, path) + except BaseException: + tmp.unlink(missing_ok=True) + raise def _token_path(config: AdLoopConfig) -> Path: @@ -342,12 +354,16 @@ def browser_login( config: AdLoopConfig, *, login_hint: str = "", - redirect_uri: str = BROWSER_REDIRECT_URI, say: Callable[[str], None] = print, open_browser: Callable[[str], Any] | None = None, - listen: Callable[[str], dict] | None = None, + listen: Callable[[str, str], dict] | None = None, + redirect_uri: str = "", ) -> Path: - """Sign in once in the browser (authorization code + PKCE) and store the refresh token.""" + """Sign in once in the browser (authorization code + PKCE) and store the refresh token. + + Without ``listen`` (tests pass one, with a ``redirect_uri``) a listener + binds a free localhost port first, and the redirect URI names that port. + """ import secrets cfg = config.microsoft_ads @@ -360,22 +376,28 @@ def browser_login( import webbrowser open_browser = webbrowser.open + listener = None if listen is None: - from adloop.oauth_redirect import RedirectTimeout, listen_once + from adloop.oauth_redirect import RedirectListener, RedirectTimeout + + try: + listener = RedirectListener(host="localhost", path="/callback", provider="Microsoft Advertising") + except OSError as exc: + raise MicrosoftAdsAuthError( + f"Cannot listen on localhost for the sign-in ({exc}); run " + "`adloop microsoft-login --device-code` instead.", error_code="port_in_use", + ) from None + redirect_uri = listener.redirect_uri - def listen(uri: str) -> dict: + def listen(_uri: str, expected_state: str) -> dict: try: - return listen_once(uri, _BROWSER_LOGIN_TIMEOUT_SECONDS, provider="Microsoft Advertising") + return listener.wait(_BROWSER_LOGIN_TIMEOUT_SECONDS, state=expected_state) except RedirectTimeout: raise MicrosoftAdsAuthError( "No sign-in arrived within 5 minutes. Run the command again.", error_code="timeout", ) from None - except OSError as exc: - raise MicrosoftAdsAuthError( - f"Cannot listen on {uri} ({exc}); close whatever uses that port, or run " - "`adloop microsoft-login --device-code`.", error_code="port_in_use", - ) from None + redirect_uri = redirect_uri or BROWSER_REDIRECT_URI state = secrets.token_urlsafe(16) verifier, challenge = _pkce_pair() url = authorize_url(config, state=state, challenge=challenge, redirect_uri=redirect_uri, login_hint=login_hint) @@ -386,7 +408,11 @@ def listen(uri: str) -> dict: open_browser(url) except Exception: # noqa: BLE001 — the URL is printed pass - query = listen(redirect_uri) + try: + query = listen(redirect_uri, state) + finally: + if listener is not None: + listener.close() if query.get("error"): description = str(query.get("error_description") or query["error"]).split("\r\n")[0] raise MicrosoftAdsAuthError(f"Microsoft did not complete the sign-in: {description}", error_code=str(query["error"])) diff --git a/src/adloop/microsoft_ads/client.py b/src/adloop/microsoft_ads/client.py index 132aacd1..c7be1121 100644 --- a/src/adloop/microsoft_ads/client.py +++ b/src/adloop/microsoft_ads/client.py @@ -10,8 +10,10 @@ ``ApiFaultDetail`` (``OperationErrors`` / ``BatchErrors``) bodies; the codes and messages are folded into one :class:`MicrosoftAdsApiError`. An expired token (codes 105/109 or HTTP 401) is refreshed once. -- **Throttling**: HTTP 429 or code 117 (CallRateExceeded) waits briefly and - retries; a long wait surfaces as an error instead of blocking the call. +- **Throttling**: HTTP 429, code 117 (CallRateExceeded, a sliding 60-second + window per customer) and Reporting code 207 (ConcurrentRequestOverLimit) + raise at once with ``retry_after`` (60 s unless Microsoft names another + wait): retrying sooner only extends the window. Reports are asynchronous: :func:`run_report` submits, polls, downloads the zipped CSV and returns its rows as dicts keyed by column name. @@ -38,11 +40,15 @@ DEVELOPER_SETTINGS_URL = "https://developers.ads.microsoft.com/Account" _TIMEOUT_SECONDS = 60 -_MAX_THROTTLE_RETRIES = 3 -_MAX_THROTTLE_WAIT_SECONDS = 10 +# Microsoft counts calls in a sliding 60-second window; its guidance is to wait +# that long before trying again. +_THROTTLE_WAIT_SECONDS = 60 # Codes that mean the access token is not (or no longer) accepted. _AUTH_CODES = {"105", "109", "AuthenticationTokenExpired", "InvalidCredentials"} -_THROTTLE_CODES = {"117", "CallRateExceeded"} +# Codes that mean the signed-in identity is the wrong kind for the account: +# its users sign in to Microsoft Advertising with Google. +_IDENTITY_CODES = {"GoogleAccountIsRequired", "IdentityTypeMismatch"} +_THROTTLE_CODES = {"117", "CallRateExceeded", "207", "ConcurrentRequestOverLimit"} _MAX_MESSAGE = 500 @@ -139,7 +145,6 @@ def ms_request( headers["CustomerAccountId"] = str(account_id) refreshed = False - throttled = 0 while True: headers["Authorization"] = f"Bearer {creds.token()}" try: @@ -175,24 +180,26 @@ def ms_request( payload = _scrub(payload, secrets) codes, message, tracking = fault_details(payload) + if set(codes) & _IDENTITY_CODES: + raise MicrosoftAdsAuthError(_google_identity_message(message), error_code="google_identity") if (status == 401 or set(codes) & _AUTH_CODES) and not refreshed: refreshed = True creds.invalidate() continue if status == 429 or set(codes) & _THROTTLE_CODES: - throttled += 1 - wait = _retry_after(response.headers) - wait = 5 if wait is None else wait - if throttled <= _MAX_THROTTLE_RETRIES and wait <= _MAX_THROTTLE_WAIT_SECONDS: - time.sleep(max(wait, 1)) - continue + wait = max(_retry_after(response.headers) or 0, _THROTTLE_WAIT_SECONDS) + concurrent = bool(set(codes) & {"207", "ConcurrentRequestOverLimit"}) raise MicrosoftAdsApiError( - "Microsoft Advertising rate limit reached" - + (f"; retry after {wait}s" if wait else "") - + ". Wait before calling again; do not retry in a loop.", + ("Microsoft Advertising is building too many reports for this customer at once" + if concurrent else "Microsoft Advertising rate limit reached") + + f"; wait {wait}s before calling again, and do not retry in a loop.", status=429, url=url, codes=codes, tracking_id=tracking, retry_after=wait, ) if status == 401 or set(codes) & _AUTH_CODES: + if set(codes) & {"105", "InvalidCredentials"}: + # The sign-in itself worked (the token refreshed), so the + # identity behind it is not a user of this account. + raise MicrosoftAdsAuthError(_google_identity_message(message), error_code="not_an_account_user") raise MicrosoftAdsAuthError( "Microsoft Advertising rejected the sign-in even after a refresh" + (f": {message}" if message else "") @@ -207,6 +214,20 @@ def ms_request( ) +def _google_identity_message(message: str) -> str: + return ( + "Microsoft Advertising does not accept the signed-in user for this account" + + (f" ({message})" if message else "") + + ". The sign-in itself worked, so the Microsoft identity AdLoop signed in with is not a user of " + "the ad account. A common cause: the account's users sign in to Microsoft Advertising with Google, " + "and a Microsoft account with the same email address is a different identity. AdLoop cannot sign " + "in with Google yet. Invite a Microsoft account or a work (Entra) user to the ad account " + "(Microsoft Advertising → Settings → Account access), accept the invitation, then run " + "`adloop microsoft-login` and sign in as that user. (Less often: microsoft_ads.developer_token is " + "wrong, or the ad account is inactive.)" + ) + + # Response fields that carry errors, also inside a successful (2xx) answer. _ERROR_KEYS = ("PartialErrors", "NestedPartialErrors", "Errors", "OperationErrors", "BatchErrors") diff --git a/src/adloop/microsoft_ads/manage.py b/src/adloop/microsoft_ads/manage.py index 0bbebef2..4c63660a 100644 --- a/src/adloop/microsoft_ads/manage.py +++ b/src/adloop/microsoft_ads/manage.py @@ -18,6 +18,11 @@ - **Multi-step applies** (a campaign and then its targeting, a list and then its attachments) report exactly what was created when a later step fails. +A plan's ``changes`` hold what the person approves (names, before → after); +request bodies, snapshots and ids live in ``ChangePlan.apply_only_payload``, +which no preview, dialog, card or audit entry shows. The dry run and the +apply read both through ``plan.apply_payload()``. + REST conventions (learn.microsoft.com/advertising/campaign-management-service): add is POST, update PUT, delete DELETE on the collection path; polymorphic objects carry a ``Type`` discriminator; on update an omitted field stays as @@ -35,26 +40,39 @@ from adloop.microsoft_ads.auth import MicrosoftAdsApiError from adloop.microsoft_ads.client import campaign_request, fault_details from adloop.microsoft_ads.read import ( + CONVERSION_BASED_STRATEGIES, _ad_groups, _ads, _bidding, _campaigns, _conversion_goals, - _criterions, _customer, _keywords, _money, account_meta, + is_negative, + target_criterions, +) +from adloop.microsoft_ads.write import _blocked as _guard +from adloop.microsoft_ads.write import ( + _validation_error, + find_entity, + store_plan_preview, ) -from adloop.microsoft_ads.write import _guard, _store, _validation_error, find_entity if TYPE_CHECKING: from adloop.config import AdLoopConfig from adloop.safety.preview import ChangePlan +# The strategies a draft can set. STRATEGIES = ("ManualCpc", "EnhancedCpc", "MaxClicks", "MaxConversions") -_SMART = {"MaxClicks", "MaxConversions"} +# Broad match needs one of these (read.CONVERSION_BASED_STRATEGIES); Maximize +# Clicks is automated but not conversion-based, so it does not count. +_CONVERSION_BASED = CONVERSION_BASED_STRATEGIES _MANUAL = {"ManualCpc", "EnhancedCpc"} +# Strategies that take a maximum CPC cap. +_CAPPED = {"MaxClicks", "MaxConversions"} +_ALTERNATIVES = "MaxClicks, EnhancedCpc or ManualCpc" MATCH_TYPES = ("Exact", "Phrase", "Broad") NEGATIVE_MATCH_TYPES = ("Exact", "Phrase") NETWORKS = ("OwnedAndOperatedOnly", "OwnedAndOperatedAndSyndicatedSearch") @@ -210,16 +228,13 @@ def step(self, what: str, fn): raise -def _base_changes(account: str, customer: str, **extra: Any) -> dict: - return {"ad_account_id": account, "customer_id": customer, **extra} - - -def _plan(operation: str, entity_type: str, entity_id: str, account: str, changes: dict, - *, warnings: list[str] | None = None, double: bool = False) -> dict: - return _store( - {"operation": operation, "entity_type": entity_type, "entity_id": str(entity_id or ""), - "customer_id": account, "requires_double_confirm": double, "changes": changes}, - warnings=warnings, +def _plan(operation: str, entity_type: str, entity_id: str, account: str, customer: str, changes: dict, + payload: dict | None = None, *, warnings: list[str] | None = None, double: bool = False) -> dict: + """Store a plan: ``changes`` for the person approving, ``payload`` for the dry run and the apply.""" + return store_plan_preview( + operation, entity_type, entity_id, account, changes, + {"ad_account_id": account, "customer_id": customer, **(payload or {})}, + warnings=warnings, double=double, ) @@ -236,7 +251,7 @@ def bidding_scheme(strategy: str, *, target_cpa: float | None, max_cpc: float | scheme: dict[str, Any] = {"Type": strategy} if strategy == "MaxConversions" and target_cpa is not None: scheme["TargetCpa"] = round(float(target_cpa), 2) - if strategy in _SMART and max_cpc is not None: + if strategy in _CAPPED and max_cpc is not None: scheme["MaxCpc"] = {"Amount": round(float(max_cpc), 2)} return scheme @@ -253,6 +268,28 @@ def _counted_goals(config: AdLoopConfig, account: str, customer: str) -> int: return sum(1 for g in goals if g.get("Status") == "Active" and not g.get("ExcludeFromBidding")) +def _no_goal_refusal(strategy: str) -> str: + return ( + f"{strategy} needs an active conversion goal that counts toward Conversions, and this account has " + "none: Microsoft refuses the campaign (ConversionGoalCriteriaNotMetForBiddingScheme). Set up a " + "conversion goal first (get_microsoft_conversion_setup shows what exists), or use " + f"{_ALTERNATIVES} for now." + ) + + +def _goals_unknown_warning(strategy: str) -> str: + return (f"The conversion goals could not be read; Microsoft refuses {strategy} without an active " + "conversion goal that counts toward Conversions.") + + +def _broad_refusal(count: int, strategy: str) -> str: + return ( + f"The campaign has {count} active broad-match keyword(s), and broad match needs conversion-based " + f"bidding (MaxConversions, MaxConversionValue or a target CPA/ROAS); {strategy} would buy whatever " + "a loose match brings. Change them to phrase or exact first." + ) + + # --------------------------------------------------------------------------- # Campaign settings # --------------------------------------------------------------------------- @@ -288,6 +325,9 @@ def update_microsoft_campaign( errors.append(f"bidding_strategy must be one of {list(STRATEGIES)}.") if target_cpa is not None and (strategy or "") not in ("", "MaxConversions"): errors.append("target_cpa goes with MaxConversions.") + if max_cpc is not None and strategy and strategy not in _CAPPED: + errors.append(f"max_cpc caps {' or '.join(sorted(_CAPPED))} bids; a {strategy} campaign's bids are set " + "on its ad groups and keywords.") template = None if tracking_url_template is None else tracking_url_template.strip() if template and not template.startswith(("http://", "https://", "{lpurl}", "{unescapedlpurl}")): errors.append("tracking_url_template must start with {lpurl}, {unescapedlpurl}, http:// or https://.") @@ -314,8 +354,14 @@ def update_microsoft_campaign( chosen = strategy or _strategy_name(current_scheme) if chosen not in STRATEGIES: return _validation_error([f"The campaign uses {chosen or 'an unknown strategy'}; pass bidding_strategy explicitly."]) + if target_cpa is not None and chosen != "MaxConversions": + return _validation_error([f"target_cpa goes with MaxConversions; this campaign uses {chosen}. Pass " + "bidding_strategy='MaxConversions' to switch."]) + if max_cpc is not None and chosen not in _CAPPED: + return _validation_error([f"max_cpc caps {' or '.join(sorted(_CAPPED))} bids; this campaign uses " + f"{chosen}, whose bids are set on its ad groups and keywords."]) has_cap = (current_scheme.get("MaxCpc") or {}).get("Amount") is not None - if max_cpc is not None and not has_cap and chosen in _SMART: + if max_cpc is not None and not has_cap and chosen in _CAPPED: return _validation_error([ "Microsoft no longer lets a campaign add a maximum CPC to automated bidding; it can " "only change or remove an existing one." @@ -329,23 +375,27 @@ def update_microsoft_campaign( update["BiddingScheme"] = scheme touched.append("BiddingScheme") shown["bidding"] = {"from": _bidding(current_scheme), "to": _bidding(scheme), "currency": meta["currency"]} - if chosen != _strategy_name(current_scheme): + switching = chosen != _strategy_name(current_scheme) + if switching: warnings.append("Changing the bid strategy restarts Microsoft's learning period; expect a week or two of unsettled results.") - if chosen == "MaxConversions" and _counted_goals(config, account, customer) == 0: - warnings.append("No active conversion goal counts toward Conversions: MaxConversions has nothing to optimize for.") + if chosen in _CONVERSION_BASED: + goals = _counted_goals(config, account, customer) + if goals == 0 and switching: + return _validation_error([_no_goal_refusal(chosen)]) + if goals == 0: + warnings.append(f"No active conversion goal counts toward Conversions: {chosen} has nothing to optimize for.") + elif goals < 0: + warnings.append(_goals_unknown_warning(chosen)) old_cap = (current_scheme.get("MaxCpc") or {}).get("Amount") new_cap = (scheme.get("MaxCpc") or {}).get("Amount") try: _check_bid(old_cap, new_cap, config) except Exception as e: # SafetyViolation return {"error": f"Maximum CPC: {e}"} - if chosen in _MANUAL: + if chosen not in _CONVERSION_BASED: broad = _active_broad_keywords(config, account, customer, campaign_id) if broad: - return _validation_error([ - f"The campaign has {len(broad)} active broad-match keyword(s); manual bidding with broad " - "match wastes spend. Change them to phrase or exact first." - ]) + return _validation_error([_broad_refusal(len(broad), chosen)]) for field, value, api_name in (("tracking_url_template", template, "TrackingUrlTemplate"), ("final_url_suffix", None if final_url_suffix is None else final_url_suffix.strip(), "FinalUrlSuffix")): if value is None or value == (campaign.get(api_name) or ""): @@ -358,10 +408,9 @@ def update_microsoft_campaign( if len(update) == 1: return {"error": "Nothing to change: pass at least one setting that differs from the campaign."} return _plan( - operation, "campaign", campaign_id, account, - _base_changes(account, customer, entity_name=campaign.get("Name"), campaign_status=campaign.get("Status"), - changes=shown, update=update, - before={k: copy.deepcopy(campaign.get(k)) for k in sorted(set(touched))}), + operation, "campaign", campaign_id, account, customer, + {"entity_name": campaign.get("Name"), "campaign_status": campaign.get("Status"), "changes": shown}, + {"update": update, "before": {k: copy.deepcopy(campaign.get(k)) for k in sorted(set(touched))}}, warnings=warnings, ) @@ -372,16 +421,16 @@ def update_microsoft_campaign( def _current_targeting(config: AdLoopConfig, account: str, customer: str, campaign_id: str) -> dict: - locations = _criterions(config, account, customer, campaign_id, "Location") + found = target_criterions(config, account, customer, campaign_id, ("Location", "LocationIntent", "DayTime")) included = {} excluded = {} - for c in locations: + for c in found["Location"]: crit = c.get("Criterion") or {} entry = {"criterion_id": str(c.get("Id")), "name": crit.get("DisplayName") or str(crit.get("LocationId"))} - target = excluded if c.get("Type") == "NegativeCampaignCriterion" else included + target = excluded if is_negative(c) else included target[str(crit.get("LocationId"))] = entry - intent = _criterions(config, account, customer, campaign_id, "LocationIntent") - schedule = _criterions(config, account, customer, campaign_id, "DayTime") + intent = found["LocationIntent"] + schedule = found["DayTime"] return { "included": included, "excluded": excluded, @@ -426,13 +475,13 @@ def _schedule_blocks(schedule: list, errors: list[str]) -> list[dict]: b["ToHour"] * 60 + list(_MINUTES.values()).index(b["ToMinute"]) * 15) for b in items) if any(a[1] > b[0] for a, b in zip(minutes, minutes[1:])): errors.append(f"ad_schedule windows on {day} overlap.") - if len(items) > 6: - errors.append(f"At most 6 ad_schedule windows on {day}.") + if len(items) > _MAX_WINDOWS_PER_DAY: + errors.append(f"At most {_MAX_WINDOWS_PER_DAY} ad_schedule windows on {day} (Microsoft's limit).") return blocks # Microsoft: "the maximum number of day and time criteria per day that you -# can set is seven" (per campaign or ad group). +# can set is seven" (per campaign or ad group; DayTimeCriterion reference). _MAX_WINDOWS_PER_DAY = 7 @@ -600,9 +649,9 @@ def update_microsoft_campaign_targeting( if not any(v for k, v in plan_ops.items() if k != "schedule_kept"): return {"error": "Nothing to change: the targeting already matches."} return _plan( - operation, "campaign", campaign_id, account, - _base_changes(account, customer, entity_name=campaign.get("Name"), changes=shown, operations=plan_ops, - before=current), + operation, "campaign", campaign_id, account, customer, + {"entity_name": campaign.get("Name"), "changes": shown}, + {"operations": plan_ops, "before": current}, warnings=warnings, double=bool(blocks) and not current["schedule"], ) @@ -648,9 +697,14 @@ def draft_microsoft_campaign( strategy = "MaxConversions" if bidding_strategy == "TargetCpa" else (bidding_strategy or "MaxConversions") if strategy not in STRATEGIES: errors.append(f"bidding_strategy must be one of {list(STRATEGIES)}.") + if target_cpa is not None and strategy != "MaxConversions": + errors.append(f"target_cpa goes with MaxConversions, not {strategy}.") langs = _clean(languages) if not langs: errors.append("languages is required, e.g. ['English']: without it ads reach every language.") + elif any(lang.lower() == "all" for lang in langs): + errors.append("languages=['All'] reaches every language; name the languages the ads are written in, " + "e.g. ['English'].") include = _clean(location_ids) if not include: errors.append("location_ids is required (search_microsoft_locations): an untargeted campaign serves everywhere.") @@ -670,8 +724,12 @@ def draft_microsoft_campaign( if name.lower() in existing: return _validation_error([f"A campaign named '{name}' already exists."]) warnings: list[str] = [] - if strategy == "MaxConversions" and _counted_goals(config, account, customer) == 0: - warnings.append("No active conversion goal counts toward Conversions: MaxConversions would have nothing to optimize for.") + if strategy in _CONVERSION_BASED: + goals = _counted_goals(config, account, customer) + if goals == 0: + return _validation_error([_no_goal_refusal(strategy)]) + if goals < 0: + warnings.append(_goals_unknown_warning(strategy)) if target_cpa is not None and target_cpa > 0 and budget < 5 * target_cpa: warnings.append(f"A daily budget below 5× the target CPA ({target_cpa}) gives bidding little to learn from.") campaign: dict[str, Any] = { @@ -696,15 +754,22 @@ def draft_microsoft_campaign( + [{"Type": "BiddableCampaignCriterion", "Criterion": {"Type": "LocationIntentCriterion", "IntentOption": location_intent}}] ) + # [AUD]: search campaigns reach the Microsoft Audience Network (Outlook, + # MSN) unless their AudienceAdsBidAdjustment is -100. + warnings.append("New search campaigns can also show on the Microsoft Audience Network (Outlook, MSN, Edge); " + "set audience_ads_bid_adjustment=-100 on its ad groups (update_microsoft_ad_group) to keep " + "it on search only.") return _plan( - operation, "campaign", "", account, - _base_changes( - account, customer, entity_name=name, status_on_create="Paused", daily_budget=budget, - currency=meta["currency"], monthly_maximum=round(budget * 30.4, 2), bidding=_bidding(campaign["BiddingScheme"]), - languages=langs, location_ids=include, excluded_location_ids=exclude, location_intent=location_intent, - time_zone=meta["time_zone"], tracking_url_template=campaign.get("TrackingUrlTemplate"), - final_url_suffix=campaign.get("FinalUrlSuffix"), campaign=campaign, criteria=criteria, - ), + operation, "campaign", "", account, customer, + { + "entity_name": name, "status_on_create": "Paused", "daily_budget": budget, "currency": meta["currency"], + "monthly_maximum": round(budget * 30.4, 2), "bidding": _bidding(campaign["BiddingScheme"]), + "languages": langs, "location_ids": include, "excluded_location_ids": exclude or None, + "location_intent": location_intent, "time_zone": meta["time_zone"], + "tracking_url_template": campaign.get("TrackingUrlTemplate"), + "final_url_suffix": campaign.get("FinalUrlSuffix"), + }, + {"campaign": campaign, "criteria": criteria}, warnings=warnings + [ "Created paused. Add ad groups, keywords, ads and extensions, then enable it.", ], @@ -753,13 +818,14 @@ def _check_bid(current: float | None, proposed: float | None, config) -> None: check_bid_increase(float(current), float(proposed), config.safety) -def _refuse_broad_on_manual(rows: list[dict], campaign: dict, errors: list[str]) -> None: +def _refuse_broad_without_conversion_bidding(rows: list[dict], campaign: dict, errors: list[str]) -> None: strategy = _strategy_name(campaign.get("BiddingScheme")) broad = [r["Text"] for r in rows if r["MatchType"] == "Broad"] - if broad and strategy not in _SMART: + if broad and strategy not in _CONVERSION_BASED: errors.append( - f"Broad match on a {strategy or 'manual'}-bid campaign wastes spend; use Phrase or Exact for " - f"{broad[:5]}, or move the campaign to MaxConversions first." + f"Broad match needs conversion-based bidding (MaxConversions, MaxConversionValue or a target " + f"CPA/ROAS); on a {strategy or 'manual'} campaign it buys whatever a loose match brings. Use Phrase " + f"or Exact for {broad[:5]}, or move the campaign to MaxConversions first." ) @@ -795,7 +861,7 @@ def draft_microsoft_ad_group( strategy = _strategy_name(campaign.get("BiddingScheme")) if strategy in _MANUAL and cpc_bid is None: errors.append(f"A {strategy} campaign needs cpc_bid for the ad group.") - _refuse_broad_on_manual(rows, campaign, errors) + _refuse_broad_without_conversion_bidding(rows, campaign, errors) names = {str(g.get("Name")).lower() for g in _ad_groups(config, account, customer, str(campaign_id))} if name.lower() in names: errors.append(f"The campaign already has an ad group named '{name}'.") @@ -808,14 +874,14 @@ def draft_microsoft_ad_group( if network == "OwnedAndOperatedAndSyndicatedSearch": warnings.append("Syndicated search partners are included; their traffic is usually weaker.") return _plan( - operation, "ad_group", "", account, - _base_changes(account, customer, entity_name=name, campaign_id=str(campaign_id), campaign_name=campaign.get("Name"), - campaign_status=campaign.get("Status"), cpc_bid=_money(group.get("CpcBid")), network=network, - status_on_create="Active (its keywords too); nothing serves until an ad in it is enabled", - currency=meta["currency"], - keywords=[f"{r['Text']} [{r['MatchType']}]" + (f" bid {r['Bid']['Amount']}" if r.get("Bid") else "") - for r in rows], - ad_group=group, keyword_rows=rows), + operation, "ad_group", "", account, customer, + {"entity_name": name, "campaign_name": campaign.get("Name"), "campaign_status": campaign.get("Status"), + "cpc_bid": _money(group.get("CpcBid")), "network": network, + "status_on_create": "Active (its keywords too); nothing serves until an ad in it is enabled", + "currency": meta["currency"], + "keywords": [f"{r['Text']} [{r['MatchType']}]" + (f" bid {r['Bid']['Amount']}" if r.get("Bid") else "") + for r in rows] or None}, + {"campaign_id": str(campaign_id), "ad_group": group, "keyword_rows": rows}, warnings=warnings, ) @@ -867,7 +933,7 @@ def update_microsoft_ad_group( update["CpcBid"] = {"Amount": round(float(cpc_bid), 2)} shown["cpc_bid"] = {"from": old, "to": round(float(cpc_bid), 2), "currency": meta["currency"]} touched.append("CpcBid") - if _strategy_name(campaign.get("BiddingScheme")) in _SMART: + if _strategy_name(campaign.get("BiddingScheme")) not in _MANUAL: warnings.append("The campaign uses automated bidding, which ignores the ad group's default bid.") if network and network != group.get("Network"): update["Network"] = network @@ -875,19 +941,22 @@ def update_microsoft_ad_group( touched.append("Network") adjust = None if audience_ads_bid_adjustment is not None and int(audience_ads_bid_adjustment) != group.get("AudienceAdsBidAdjustment"): + from adloop.microsoft_ads.read import audience_network + adjust = int(audience_ads_bid_adjustment) update["AudienceAdsBidAdjustment"] = adjust - shown["audience_network"] = {"from": group.get("AudienceAdsBidAdjustment"), "to": adjust, + now = audience_network(group, campaign) + was = ("off" if not now["on"] else f"{now['bid_adjustment'] or 0:+d}%") + f" (set on the {now['set_on']})" + shown["audience_network"] = {"from": was, "to": adjust, "meaning": "off" if adjust == -100 else f"{adjust:+d}% bids on the Audience Network"} touched.append("AudienceAdsBidAdjustment") if len(update) == 1: return {"error": "Nothing to change: pass at least one setting that differs from the ad group."} return _plan( - operation, "ad_group", str(ad_group_id), account, - _base_changes(account, customer, entity_name=group.get("Name"), campaign_id=str(campaign.get("Id")), - campaign_name=campaign.get("Name"), changes=shown, update=update, - update_audience_adjustment=adjust is not None, - before={k: copy.deepcopy(group.get(k)) for k in sorted(set(touched))}), + operation, "ad_group", str(ad_group_id), account, customer, + {"entity_name": group.get("Name"), "campaign_name": campaign.get("Name"), "changes": shown}, + {"campaign_id": str(campaign.get("Id")), "update": update, "update_audience_adjustment": adjust is not None, + "before": {k: copy.deepcopy(group.get(k)) for k in sorted(set(touched))}}, warnings=warnings, ) @@ -911,7 +980,7 @@ def draft_microsoft_keywords( if not found: return {"error": f"Microsoft ad group '{ad_group_id}' was not found in account {account}."} group, campaign = found["entity"], found["campaign"] - _refuse_broad_on_manual(rows, campaign, errors) + _refuse_broad_without_conversion_bidding(rows, campaign, errors) if errors: return _validation_error(errors) existing = {(str(k.get("Text")).lower(), k.get("MatchType")) for k in _keywords(config, account, customer, str(ad_group_id)) @@ -936,13 +1005,12 @@ def draft_microsoft_keywords( warnings.append("The keywords are added Active and the ad group and campaign are active, so they can serve " "as soon as this is applied (once the ad group has an enabled ad).") return _plan( - operation, "ad_group", str(ad_group_id), account, - _base_changes(account, customer, entity_name=group.get("Name"), campaign_name=campaign.get("Name"), - status_on_create="Active", ad_group_status=group.get("Status"), - campaign_status=campaign.get("Status"), - keywords=[f"{r['Text']} [{r['MatchType']}]" + (f" bid {r['Bid']['Amount']}" if r.get("Bid") else "") - for r in new_rows], - keyword_rows=new_rows), + operation, "ad_group", str(ad_group_id), account, customer, + {"entity_name": group.get("Name"), "campaign_name": campaign.get("Name"), "status_on_create": "Active", + "ad_group_status": group.get("Status"), "campaign_status": campaign.get("Status"), + "keywords": [f"{r['Text']} [{r['MatchType']}]" + (f" bid {r['Bid']['Amount']}" if r.get("Bid") else "") + for r in new_rows]}, + {"campaign_id": str(campaign.get("Id")), "keyword_rows": new_rows}, warnings=warnings, ) @@ -972,7 +1040,7 @@ def update_microsoft_keyword_bids( found = find_entity(config, account, customer, "ad_group", str(ad_group_id)) if not found: return {"error": f"Microsoft ad group '{ad_group_id}' was not found in account {account}."} - group = found["entity"] + group, campaign = found["entity"], found["campaign"] keywords = {str(k.get("Id")): k for k in _keywords(config, account, customer, str(ad_group_id))} missing = [k for k in wanted if k not in keywords] if missing: @@ -993,9 +1061,10 @@ def update_microsoft_keyword_bids( "from": current, "to": bid if bid is not None else f"ad group default {default_bid}"}) before[kid] = copy.deepcopy(keywords[kid].get("Bid")) return _plan( - operation, "ad_group", str(ad_group_id), account, - _base_changes(account, customer, entity_name=group.get("Name"), currency=meta["currency"], bids=shown, - keyword_rows=rows, before=before, default_bid_before=copy.deepcopy(group.get("CpcBid"))), + operation, "ad_group", str(ad_group_id), account, customer, + {"entity_name": group.get("Name"), "currency": meta["currency"], "bids": shown}, + {"campaign_id": str(campaign.get("Id")), "keyword_rows": rows, "before": before, + "default_bid_before": copy.deepcopy(group.get("CpcBid"))}, ) @@ -1143,10 +1212,11 @@ def add_microsoft_negative_keywords( if conflicts: warnings.append(f"These negatives block active keywords: {conflicts[:10]}.") return _plan( - operation, kind, str(entity.get("Id")), account, - _base_changes(account, customer, entity_name=entity.get("Name"), entity_kind=entity_type, - parent_id=str(campaign.get("Id")), - negatives=[f"{r['Text']} [{r['MatchType']}]" for r in new_rows], negative_rows=new_rows), + operation, kind, str(entity.get("Id")), account, customer, + {"entity_name": entity.get("Name"), + "campaign_name": campaign.get("Name") if kind == "ad_group" else None, + "negatives": [f"{r['Text']} [{r['MatchType']}]" for r in new_rows]}, + {"entity_kind": entity_type, "campaign_id": str(campaign.get("Id")), "negative_rows": new_rows}, warnings=warnings, ) @@ -1191,9 +1261,10 @@ def propose_microsoft_negative_keyword_list( else: warnings.append("The list is attached to no campaign, so it blocks nothing until attached.") return _plan( - operation, "negative_keyword_list", "", account, - _base_changes(account, customer, entity_name=list_name, negatives=[f"{r['Text']} [{r['MatchType']}]" for r in rows], - attach_to=[campaigns[c].get("Name") for c in cids], campaign_ids=cids, negative_rows=rows), + operation, "negative_keyword_list", "", account, customer, + {"entity_name": list_name, "negatives": [f"{r['Text']} [{r['MatchType']}]" for r in rows], + "attach_to": [campaigns[c].get("Name") for c in cids]}, + {"campaign_ids": cids, "negative_rows": rows}, warnings=warnings, ) @@ -1228,9 +1299,10 @@ def add_to_microsoft_negative_keyword_list( if conflicts: warnings.append(f"These negatives block active keywords: {conflicts[:10]}.") return _plan( - operation, "negative_keyword_list", str(list_id), account, - _base_changes(account, customer, entity_name=lists[str(list_id)].get("Name"), attached_campaigns=len(attached), - negatives=[f"{r['Text']} [{r['MatchType']}]" for r in new_rows], negative_rows=new_rows), + operation, "negative_keyword_list", str(list_id), account, customer, + {"entity_name": lists[str(list_id)].get("Name"), "attached_campaigns": len(attached), + "negatives": [f"{r['Text']} [{r['MatchType']}]" for r in new_rows]}, + {"negative_rows": new_rows}, warnings=warnings, ) @@ -1260,9 +1332,9 @@ def _draft_list_link(config, *, attach: bool, ad_account_id: str, list_id: str, if not attach: warnings.append("Detached campaigns stop blocking these negatives; the list itself stays.") return _plan( - operation, "negative_keyword_list", str(list_id), account, - _base_changes(account, customer, entity_name=lists[str(list_id)].get("Name"), - campaigns=[campaigns[c].get("Name") for c in targets], campaign_ids=targets), + operation, "negative_keyword_list", str(list_id), account, customer, + {"entity_name": lists[str(list_id)].get("Name"), "campaigns": [campaigns[c].get("Name") for c in targets]}, + {"campaign_ids": targets}, warnings=warnings, ) @@ -1364,12 +1436,13 @@ def draft_microsoft_responsive_search_ad( ad.pop("Path2", None) warnings.append("No display paths: path1/path2 make the display URL more specific.") return _plan( - operation, "ad_group", str(ad_group_id), account, - _base_changes(account, customer, entity_name=group.get("Name"), campaign_name=campaign.get("Name"), - status_on_create="Paused", - headlines=[l["Asset"]["Text"] + (f" [pinned {l['PinnedField']}]" if l.get("PinnedField") else "") for l in fields["Headlines"]], - descriptions=[l["Asset"]["Text"] for l in fields["Descriptions"]], - final_url=fields["FinalUrls"][0], path1=ad.get("Path1"), path2=ad.get("Path2"), ad=ad), + operation, "ad_group", str(ad_group_id), account, customer, + {"entity_name": group.get("Name"), "campaign_name": campaign.get("Name"), "status_on_create": "Paused", + "headlines": [l["Asset"]["Text"] + (f" [pinned {l['PinnedField']}]" if l.get("PinnedField") else "") + for l in fields["Headlines"]], + "descriptions": [l["Asset"]["Text"] for l in fields["Descriptions"]], + "final_url": fields["FinalUrls"][0], "path1": ad.get("Path1"), "path2": ad.get("Path2")}, + {"campaign_id": str(campaign.get("Id")), "ad": ad}, warnings=warnings, ) @@ -1394,7 +1467,7 @@ def update_microsoft_responsive_search_ad( found = find_entity(config, account, customer, "ad", str(ad_id)) if not found: return {"error": f"Microsoft ad '{ad_id}' was not found in account {account}."} - ad, group = found["entity"], found["ad_group"] + ad, group, campaign = found["entity"], found["ad_group"], found["campaign"] if ad.get("Type") != "ResponsiveSearch": return _validation_error([f"Ad {ad_id} is a {ad.get('Type')} ad; only responsive search ads are edited here."]) shown = {} @@ -1406,11 +1479,12 @@ def update_microsoft_responsive_search_ad( shown[key.lower()] = {"from": ad.get(key), "to": value} warnings.append("Edited ads go back to Microsoft's editorial review.") return _plan( - operation, "ad", str(ad_id), account, - _base_changes(account, customer, entity_name=f"RSA {ad_id}", ad_group_id=str(group.get("Id")), - ad_group_name=group.get("Name"), changes=shown, - update={"Type": "ResponsiveSearch", "Id": str(ad_id), **fields}, - before={k: copy.deepcopy(ad.get(k)) for k in fields}), + operation, "ad", str(ad_id), account, customer, + {"entity_name": f"RSA {ad_id}", "ad_group_name": group.get("Name"), "campaign_name": campaign.get("Name"), + "changes": shown}, + {"campaign_id": str(campaign.get("Id")), "ad_group_id": str(group.get("Id")), + "update": {"Type": "ResponsiveSearch", "Id": str(ad_id), **fields}, + "before": {k: copy.deepcopy(ad.get(k)) for k in fields}}, warnings=warnings, ) @@ -1484,9 +1558,9 @@ def key(ext): # noqa: E306 if len(new) < len(extensions): warnings.append(f"Skipped {len(extensions) - len(new)} already on {where}.") return _plan( - operation, association.lower(), entity_id, account, - _base_changes(account, customer, entity_name=where, association_type=association, entity_id=entity_id, - **shown, extensions=new), + operation, _ASSOCIATION_ENTITY[association], entity_id, account, customer, + {"entity_name": where, **shown}, + {"association_type": association, "entity_id": entity_id, "extensions": new}, warnings=warnings, ) @@ -1845,9 +1919,9 @@ def draft_microsoft_image_extension( shown["final_url"] = url or "the ad's own final URL" shown["layouts"] = layouts return _plan( - operation, _ASSOCIATION_ENTITY[association], entity_id, account, - _base_changes(account, customer, entity_name=where, association_type=association, entity_id=entity_id, - **shown, image_payloads=images), + operation, _ASSOCIATION_ENTITY[association], entity_id, account, customer, + {"entity_name": where, **shown}, + {"association_type": association, "entity_id": entity_id, "image_payloads": images}, warnings=warnings, ) @@ -1987,6 +2061,50 @@ def get_microsoft_ad_extensions(config: AdLoopConfig, *, ad_account_id: str = "" "campaign_criterion", "extension_association") +# Criterion types a campaign_criterion remove_id can point at, looked up in +# this order (one query each, until the criterion is found). +_CRITERION_KINDS = ("Location", "Radius", "DayTime", "LocationIntent", "Age", "Gender", "Device") + + +def _find_criterion(by_kind: dict[str, list[dict]], criterion_id: str) -> dict | None: + """The criterion with this id among a campaign's target criteria, with the others of its kind.""" + for kind, rows in by_kind.items(): + for row in rows: + if str(row.get("Id")) == str(criterion_id): + return {"criterion": row, "kind": kind, "siblings": rows} + return None + + +def _criterion_label(row: dict, kind: str) -> str: + crit = row.get("Criterion") or {} + side = "excluded" if is_negative(row) else "targeted" + if kind == "Location": + return f"location {crit.get('DisplayName') or crit.get('LocationId')} ({side})" + if kind == "Radius": + return f"radius {crit.get('Name') or ''} {crit.get('Radius')} {crit.get('RadiusUnit') or ''} ({side})".replace(" ", " ") + if kind == "DayTime": + return f"ad schedule window {_block_label(crit)}" + if kind == "LocationIntent": + return f"location intent {crit.get('IntentOption')}" + return f"{kind.lower()} criterion {row.get('Id')}" + + +def _positive_locations(rows: list[dict]) -> list[dict]: + return [r for r in rows if not is_negative(r)] + + +def _criterion_refusal(campaign_name: str, found: dict, by_kind: dict[str, list[dict]]) -> str | None: + """Why removing this criterion must go through update_microsoft_campaign_targeting, or None.""" + if found["kind"] not in ("Location", "Radius") or is_negative(found["criterion"]): + return None + positives = _positive_locations(by_kind.get("Location", []) + by_kind.get("Radius", [])) + others = [r for r in positives if str(r.get("Id")) != str(found["criterion"].get("Id"))] + if others: + return None + return (f"This is the last targeted location of campaign '{campaign_name}': without it the campaign " + "serves everywhere. Use update_microsoft_campaign_targeting with the full location list instead.") + + def remove_microsoft_entity(config: AdLoopConfig, *, ad_account_id: str = "", entity_type: str = "", entity_id: str = "") -> dict: """Draft deleting an entity (irreversible; double confirmation).""" operation = "microsoft_remove_entity" @@ -2001,15 +2119,20 @@ def remove_microsoft_entity(config: AdLoopConfig, *, ad_account_id: str = "", en return _validation_error(["entity_id is required."]) meta, account, customer = _ctx(config, ad_account_id) shown: dict[str, Any] = {} + payload: dict[str, Any] = {} request: dict[str, Any] + warnings: list[str] = [] if entity_type in ("campaign", "ad_group", "ad", "keyword"): found = find_entity(config, account, customer, entity_type, entity_id) if not found: return {"error": f"Microsoft {entity_type.replace('_', ' ')} '{entity_id}' was not found."} entity = found["entity"] label = entity.get("Name") or entity.get("Text") or f"{entity.get('Type')} ad {entity_id}" - shown = {"name": label, "campaign": found["campaign"].get("Name"), - "ad_group": (found.get("ad_group") or {}).get("Name"), "current_status": entity.get("Status")} + shown = {"name": label, "campaign_name": found["campaign"].get("Name") if entity_type != "campaign" else None, + "ad_group_name": (found.get("ad_group") or {}).get("Name") if entity_type in ("ad", "keyword") else None, + "current_status": entity.get("Status")} + payload = {"campaign_id": str(found["campaign"].get("Id")), + "ad_group_id": str((found.get("ad_group") or {}).get("Id") or "")} if entity_type == "campaign": request = {"path": "Campaigns", "body": {"AccountId": account, "CampaignIds": [entity_id]}} elif entity_type == "ad_group": @@ -2018,6 +2141,7 @@ def remove_microsoft_entity(config: AdLoopConfig, *, ad_account_id: str = "", en request = {"path": "Ads", "body": {"AdGroupId": str(found["ad_group"].get("Id")), "AdIds": [entity_id]}} else: request = {"path": "Keywords", "body": {"AdGroupId": str(found["ad_group"].get("Id")), "KeywordIds": [entity_id]}} + warnings.append("Deleting cannot be undone; pausing keeps the history and lets it come back.") else: parts = entity_id.split("~") if entity_type == "negative_keyword" and len(parts) == 3 and parts[0] in ("Campaign", "AdGroup"): @@ -2030,17 +2154,37 @@ def remove_microsoft_entity(config: AdLoopConfig, *, ad_account_id: str = "", en request = {"path": "ListItems", "body": {"ListItemIds": [int(item)], "SharedList": {"Type": _LIST_TYPE, "Id": int(list_id)}, "SharedEntityScope": "Account"}} shown = {"list_id": list_id, "item_id": item} - elif entity_type == "campaign_criterion" and len(parts) == 2: + elif entity_type == "campaign_criterion" and len(parts) == 2 and all(x.isdigit() for x in parts): cid, crit = parts + campaign = find_entity(config, account, customer, "campaign", cid) + if not campaign: + return {"error": f"Microsoft campaign '{cid}' was not found in account {account}."} + name = campaign["entity"].get("Name") + by_kind = target_criterions(config, account, customer, cid, _CRITERION_KINDS) + found = _find_criterion(by_kind, crit) + if not found: + return {"error": f"Campaign '{name}' has no target criterion {crit} (get_microsoft_campaigns lists them)."} + refusal = _criterion_refusal(name, found, by_kind) + if refusal: + return _validation_error([refusal]) + label = _criterion_label(found["criterion"], found["kind"]) + shown = {"name": label, "campaign_name": name, "criterion_type": found["kind"]} + payload = {"campaign_id": cid, "criterion_kind": found["kind"]} request = {"path": "CampaignCriterions", "body": {"CampaignCriterionIds": [int(crit)], "CampaignId": int(cid), "CriterionType": "Targets"}} - shown = {"campaign_id": cid, "criterion_id": crit} + if found["kind"] == "LocationIntent": + warnings.append("Without its location intent the campaign falls back to Microsoft's default, " + "which also reaches people outside the locations who search for them.") + if found["kind"] == "DayTime" and len(found["siblings"]) == 1: + warnings.append("This is the campaign's last ad schedule window: without it the campaign serves at all hours.") elif entity_type == "extension_association" and len(parts) == 3 and parts[2] in _ASSOCIATION_ENTITY: ext, owner, association = parts request = {"path": "AdExtensionsAssociations", "body": {"AccountId": account, "AssociationType": association, "AdExtensionIdToEntityIdAssociations": [ {"AdExtensionId": int(ext), "EntityId": int(owner)}]}} shown = {"extension_id": ext, "removed_from": f"{association} {owner}"} + warnings.append("This unlinks the extension only; the extension (and an image extension's images) " + "stays in the account's library.") else: return _validation_error([ "entity_id format: negative_keyword 'Campaign~~' or 'AdGroup~~', " @@ -2048,14 +2192,9 @@ def remove_microsoft_entity(config: AdLoopConfig, *, ad_account_id: str = "", en "extension_association '~~' (the remove_id values the read " "tools return)." ]) - warnings = ["Deleting cannot be undone; pausing keeps the history and lets it come back."] if entity_type in ( - "campaign", "ad_group", "ad", "keyword") else [] - if entity_type == "extension_association": - warnings.append("This unlinks the extension only; the extension (and an image extension's images) " - "stays in the account's library.") - return _plan(operation, entity_type, entity_id, account, - _base_changes(account, customer, entity_name=shown.get("name") or entity_id, target=shown, request=request), - warnings=warnings, double=True) + return _plan(operation, entity_type, entity_id, account, customer, + {"entity_name": shown.pop("name", None) or entity_id, **shown}, + {**payload, "request": request}, warnings=warnings, double=True) # --------------------------------------------------------------------------- @@ -2083,13 +2222,16 @@ def preflight(config: AdLoopConfig, plan: ChangePlan) -> dict: """Re-read what the plan touches and re-check the gates; sends nothing.""" from adloop.safety.guards import check_budget_cap - c = plan.changes or {} + c = plan.apply_payload() account, customer = c["ad_account_id"], c.get("customer_id", "") op = plan.operation checks: dict[str, Any] = {"ad_account_id": account} def entity(kind: str, eid: str) -> dict: - found = find_entity(config, account, customer, kind, eid) + # The plan's stored parents keep this to three reads, not a scan of the account. + parent = c.get("ad_group_id", "") if kind in ("keyword", "ad") else "" + found = find_entity(config, account, customer, kind, eid, parent_id=parent or "", + campaign_id=c.get("campaign_id", "") if kind != "campaign" else "") if not found: raise ValueError(f"{kind.replace('_', ' ')} '{eid}' no longer exists.") return found @@ -2101,17 +2243,15 @@ def entity(kind: str, eid: str) -> dict: if scheme: _check_bid((((campaign.get("BiddingScheme") or {}).get("MaxCpc")) or {}).get("Amount"), (scheme.get("MaxCpc") or {}).get("Amount"), config) - if scheme.get("Type") in _MANUAL and _active_broad_keywords(config, account, customer, plan.entity_id): - raise ValueError("The campaign now has active broad-match keywords; manual bidding with broad match " - "wastes spend. Change them to phrase or exact first.") + strategy = _strategy_name(scheme) + if strategy not in _CONVERSION_BASED: + broad = _active_broad_keywords(config, account, customer, plan.entity_id) + if broad: + raise ValueError(_broad_refusal(len(broad), strategy).replace("The campaign has", "The campaign now has")) + elif (strategy != _strategy_name(c["before"].get("BiddingScheme")) + and _counted_goals(config, account, customer) == 0): + raise ValueError(_no_goal_refusal(strategy)) elif op == "microsoft_update_targeting": - ops = c.get("operations") or {} - scheduled = {str(s.get("criterion_id")) for s in (c["before"].get("schedule") or [])} - if (any(((x.get("Criterion") or {}).get("Type")) == "DayTimeCriterion" for x in ops.get("add") or []) - or any(str(i) in scheduled for i in ops.get("delete") or [])): - raise ValueError("This plan changes the ad schedule and was drafted by an earlier AdLoop version, " - "which did not check the schedule's time zone mode or order the windows Microsoft " - "allows; draft it again.") campaign = entity("campaign", plan.entity_id)["entity"] now = _current_targeting(config, account, customer, plan.entity_id) if "searcher_time_zone" in c["before"]: @@ -2125,13 +2265,19 @@ def entity(kind: str, eid: str) -> dict: check_budget_cap(float(c["daily_budget"]), config.safety) if c["entity_name"].lower() in {str(x.get("Name")).lower() for x in _campaigns(config, account, customer)}: raise ValueError(f"A campaign named '{c['entity_name']}' now exists (an earlier attempt may have created it).") + strategy = _strategy_name(c["campaign"].get("BiddingScheme")) + if strategy in _CONVERSION_BASED: + goals = _counted_goals(config, account, customer) + if goals == 0: + raise ValueError(_no_goal_refusal(strategy)) + checks["conversion_goals"] = goals if goals >= 0 else "unknown" checks["budget_cap_ok"] = True elif op == "microsoft_create_ad_group": campaign = entity("campaign", c["campaign_id"])["entity"] if c["entity_name"].lower() in {str(g.get("Name")).lower() for g in _ad_groups(config, account, customer, c["campaign_id"])}: raise ValueError(f"An ad group named '{c['entity_name']}' now exists in the campaign.") errors = [] - _refuse_broad_on_manual(c["keyword_rows"], campaign, errors) + _refuse_broad_without_conversion_bidding(c["keyword_rows"], campaign, errors) if _strategy_name(campaign.get("BiddingScheme")) in _MANUAL and not c["ad_group"].get("CpcBid"): errors.append("The campaign now uses manual bidding, which needs a default bid for the ad group.") if errors: @@ -2144,7 +2290,7 @@ def entity(kind: str, eid: str) -> dict: elif op == "microsoft_add_keywords": found = entity("ad_group", plan.entity_id) errors = [] - _refuse_broad_on_manual(c["keyword_rows"], found["campaign"], errors) + _refuse_broad_without_conversion_bidding(c["keyword_rows"], found["campaign"], errors) if errors: raise ValueError("; ".join(errors)) have = {(str(k.get("Text")).lower(), k.get("MatchType")) for k in _keywords(config, account, customer, plan.entity_id) @@ -2243,6 +2389,16 @@ def key(ext): # noqa: E306 elif op == "microsoft_remove_entity": if plan.entity_type in ("campaign", "ad_group", "ad", "keyword"): entity(plan.entity_type, plan.entity_id) + elif plan.entity_type == "campaign_criterion": + cid, crit = plan.entity_id.split("~") + name = entity("campaign", cid)["entity"].get("Name") + by_kind = target_criterions(config, account, customer, cid, _CRITERION_KINDS) + found = _find_criterion(by_kind, crit) + if not found: + raise ValueError(f"Criterion {crit} is no longer on campaign '{name}'.") + refusal = _criterion_refusal(name, found, by_kind) + if refusal: + raise ValueError(refusal) else: raise ValueError(f"Unknown Microsoft operation: {op}") checks["checked"] = op.replace("microsoft_", "") @@ -2251,7 +2407,7 @@ def key(ext): # noqa: E306 def apply_plan(config: AdLoopConfig, plan: ChangePlan) -> dict: """Execute a management plan (after :func:`preflight`, which the caller runs first).""" - c = plan.changes or {} + c = plan.apply_payload() account = c["ad_account_id"] op = plan.operation progress = _Progress() diff --git a/src/adloop/microsoft_ads/read.py b/src/adloop/microsoft_ads/read.py index 857820a1..421bad0e 100644 --- a/src/adloop/microsoft_ads/read.py +++ b/src/adloop/microsoft_ads/read.py @@ -32,6 +32,13 @@ # outside Microsoft's in-store pilot, which is almost all of them. _IN_STORE_PILOT_CODES = {"InStoreTransactionPilotNotEnabledForCustomer", "5359"} +# Bid strategies that optimise for conversions (BiddingScheme Type without its +# "BiddingScheme" suffix). Broad match is only safe under these: Maximize +# Clicks and manual bids buy whatever traffic a loose match brings. TargetCpa +# and TargetRoas are the older stand-alone schemes Microsoft folded into +# MaxConversions and MaxConversionValue; campaigns can still carry them. +CONVERSION_BASED_STRATEGIES = frozenset({"MaxConversions", "MaxConversionValue", "TargetCpa", "TargetRoas", "MaxRoas"}) + # Microsoft time zone names → IANA, for "today" in the account's zone. Reports # take Microsoft's own name (ReportTimeZone) directly. From Microsoft's time # zone mapping table (advertising/scripts/concepts/timezone-mapping), plus the @@ -179,10 +186,6 @@ # --------------------------------------------------------------------------- -def reset_account_cache() -> None: - _account_cache.clear() - - def resolve_account(config: AdLoopConfig, ad_account_id: str = "") -> str: account = str(ad_account_id or config.microsoft_ads.ad_account_id or "").strip() if not account: @@ -390,6 +393,42 @@ def _criterions(config: AdLoopConfig, account: str, customer: str, campaign_id: return [c for c in payload.get("CampaignCriterions") or [] if isinstance(c, dict)] +def criterion_kind(c: dict) -> str: + """'Location', 'Radius', 'DayTime', ...: reads name criteria without the 'Criterion' suffix.""" + kind = str((c.get("Criterion") or {}).get("Type") or "") + return kind.removesuffix("Criterion") + + +def is_negative(c: dict) -> bool: + return str(c.get("Type") or "").startswith("Negative") + + +TARGET_KINDS = ("Location", "LocationIntent", "Radius", "DayTime") +# One "Targets" query returns every target criterion of a campaign instead of +# one call per type. If Microsoft ever refuses it, the per-type queries take +# over for the rest of the process. +_targets_query = {"refused": False} + + +def target_criterions(config: AdLoopConfig, account: str, customer: str, campaign_id: str, + kinds: tuple[str, ...] = TARGET_KINDS) -> dict[str, list[dict]]: + """A campaign's target criteria by kind, in one call where Microsoft allows it.""" + if not _targets_query["refused"]: + try: + rows = _criterions(config, account, customer, campaign_id, "Targets") + except MicrosoftAdsApiError as exc: + if exc.status != 400: + raise + _targets_query["refused"] = True + else: + out: dict[str, list[dict]] = {k: [] for k in kinds} + for row in rows: + if criterion_kind(row) in out: + out[criterion_kind(row)].append(row) + return out + return {k: _criterions(config, account, customer, campaign_id, k) for k in kinds} + + def _ad_groups(config: AdLoopConfig, account: str, customer: str, campaign_id: str) -> list[dict]: payload = campaign_request( config, "AdGroups/QueryByCampaignId", {"CampaignId": campaign_id}, @@ -445,13 +484,13 @@ def _location_summary(locations: list[dict], intent: list[dict], radius: list[di included, excluded = [], [] for c in locations + radius: crit = c.get("Criterion") or {} - if crit.get("Type") == "RadiusCriterion": + if criterion_kind(c) == "Radius": label = f"{crit.get('Name') or 'radius'} ({crit.get('Radius')} {crit.get('RadiusUnit') or ''})".strip() else: label = crit.get("DisplayName") or str(crit.get("LocationId") or "") if crit.get("LocationType"): label += f" ({crit.get('LocationType')})" - (excluded if c.get("Type") == "NegativeCampaignCriterion" else included).append(label) + (excluded if is_negative(c) else included).append(label) option = "" for c in intent: option = str((c.get("Criterion") or {}).get("IntentOption") or "") @@ -494,12 +533,9 @@ def get_microsoft_campaigns( for c in _campaigns(config, account, customer, with_goals=True): targeting = None if include_targeting: - cid = str(c.get("Id")) - targeting = _location_summary( - _criterions(config, account, customer, cid, "Location"), - _criterions(config, account, customer, cid, "LocationIntent"), - _criterions(config, account, customer, cid, "Radius"), - ) + found = target_criterions(config, account, customer, str(c.get("Id")), + ("Location", "LocationIntent", "Radius")) + targeting = _location_summary(found["Location"], found["LocationIntent"], found["Radius"]) rows.append(campaign_summary(c, targeting)) insights: list[str] = [] @@ -555,6 +591,7 @@ def get_microsoft_ad_groups(config: AdLoopConfig, *, ad_account_id: str = "", ca account, customer = meta["ad_account_id"], _customer(config, meta) rows = [] for g, c in load_ad_groups(config, account, customer, campaign_id.strip()): + audience = audience_network(g, c) rows.append({ "ad_group_id": str(g.get("Id")), "name": g.get("Name"), @@ -566,6 +603,7 @@ def get_microsoft_ad_groups(config: AdLoopConfig, *, ad_account_id: str = "", ca "network": g.get("Network"), "language": g.get("Language"), "audience_ads_bid_adjustment": g.get("AudienceAdsBidAdjustment"), + "audience_network": audience, "start_date": _ms_date(g.get("StartDate")), "end_date": _ms_date(g.get("EndDate")), }) @@ -577,10 +615,7 @@ def get_microsoft_ad_groups(config: AdLoopConfig, *, ad_account_id: str = "", ca "(OwnedAndOperatedAndSyndicatedSearch); set OwnedAndOperatedOnly to keep ads on Bing, " "Yahoo and AOL only." ) - audience = [ - r for r in rows - if r["status"] == "Active" and r["audience_ads_bid_adjustment"] not in (None, -100) - ] + audience = [r for r in rows if r["status"] == "Active" and r["audience_network"]["on"]] if audience: insights.append( f"{len(audience)} active ad group(s) can show on the Microsoft Audience Network " @@ -593,6 +628,19 @@ def get_microsoft_ad_groups(config: AdLoopConfig, *, ad_account_id: str = "", ca "total_ad_groups": len(rows), "insights": insights} +def audience_network(group: dict, campaign: dict) -> dict: + """Whether an ad group can show on the Microsoft Audience Network, and where that is set. + + An ad group without its own AudienceAdsBidAdjustment inherits the + campaign's; -100 switches the Audience Network off, any other value + (or none at either level, Microsoft's default) leaves it on. + """ + own, inherited = group.get("AudienceAdsBidAdjustment"), campaign.get("AudienceAdsBidAdjustment") + effective = own if own is not None else inherited + source = "ad group" if own is not None else "campaign" if inherited is not None else "Microsoft default" + return {"on": effective != -100, "bid_adjustment": effective, "set_on": source} + + def get_microsoft_keywords( config: AdLoopConfig, *, ad_account_id: str = "", campaign_id: str = "", ad_group_id: str = "", ) -> dict: @@ -628,12 +676,13 @@ def get_microsoft_keywords( broad_manual = [ r for r in rows if r["match_type"] == "Broad" and r["status"] == "Active" - and r["campaign_bidding"] in ("ManualCpc", "EnhancedCpc") + and r["campaign_bidding"] not in CONVERSION_BASED_STRATEGIES ] if broad_manual: insights.append( - f"{len(broad_manual)} active broad-match keyword(s) sit in manual-bid campaigns, the " - "combination that wastes the most spend; use phrase/exact or a conversion-based strategy." + f"{len(broad_manual)} active broad-match keyword(s) sit in campaigns without conversion-based " + "bidding (manual bids or Maximize Clicks), the combination that wastes the most spend; use " + "phrase/exact, or move the campaign to MaxConversions or MaxConversionValue." ) return {"ad_account_id": account, "currency": meta["currency"], "keywords": rows, "total_keywords": len(rows), "insights": insights} diff --git a/src/adloop/microsoft_ads/write.py b/src/adloop/microsoft_ads/write.py index 525b29db..7eb7044c 100644 --- a/src/adloop/microsoft_ads/write.py +++ b/src/adloop/microsoft_ads/write.py @@ -12,6 +12,10 @@ Microsoft Advertising between the preview (or the dry run) and the apply is refused instead of overwritten. Updates send only the fields that change; Microsoft leaves every field it does not receive as it was. + +A plan's ``changes`` hold only what the person approves; the ids and request +bodies the dry run and the apply need sit in ``ChangePlan.apply_only_payload`` +(never shown or logged), and both read :meth:`ChangePlan.apply_payload`. """ from __future__ import annotations @@ -35,7 +39,6 @@ from adloop.safety.preview import ChangePlan PLATFORM = "microsoft" -OPERATION_PREFIX = "microsoft_" ENTITY_TYPES = ("campaign", "ad_group", "keyword", "ad") _STATUS = {"pause": "Paused", "enable": "Active"} @@ -44,40 +47,48 @@ def _validation_error(details: list[str]) -> dict: return {"error": "Validation failed", "details": details} -def _guard(operation: str, config: AdLoopConfig) -> dict | None: - from adloop.safety.guards import SafetyViolation, check_blocked_operation +def store_plan_preview(operation: str, entity_type: str, entity_id: str, account: str, changes: dict, + payload: dict, *, warnings: list[str] | None = None, double: bool = False) -> dict: + """Store a Microsoft plan: ``changes`` is what the person approves, ``payload`` what the apply sends.""" + from adloop.safety.guards import store_draft + from adloop.safety.preview import ChangePlan - try: - check_blocked_operation(operation, config.safety) - except SafetyViolation as e: - return {"error": str(e)} - return None + plan = ChangePlan( + platform=PLATFORM, operation=operation, entity_type=entity_type, entity_id=str(entity_id or ""), + customer_id=account, requires_double_confirm=double, + changes={k: v for k, v in changes.items() if v is not None}, + apply_only_payload=payload, + ) + return store_draft(plan, warnings=warnings) -def _store(plan_kwargs: dict, *, warnings: list[str] | None = None) -> dict: - from adloop.safety.preview import ChangePlan, store_plan +def _blocked(operation: str, config: AdLoopConfig) -> dict | None: + from adloop.safety.guards import blocked_operation_error - plan = ChangePlan(platform=PLATFORM, **plan_kwargs) - store_plan(plan) - preview = plan.to_preview() - if warnings: - preview["warnings"] = warnings - return preview + return blocked_operation_error(operation, config.safety) def find_entity( config: AdLoopConfig, account: str, customer: str, entity_type: str, entity_id: str, - *, parent_id: str = "", + *, parent_id: str = "", campaign_id: str = "", ) -> dict | None: - """Locate an entity and its parents; ad groups, keywords and ads carry no parent id.""" + """Locate an entity and its parents; ad groups, keywords and ads carry no parent id. + + ``parent_id`` (the ad group of a keyword or ad, or the campaign of an ad + group) and ``campaign_id`` narrow the search: a plan that stored them + finds its entity in three calls instead of reading every ad group of + the account. + """ entity_id = str(entity_id) + if entity_type == "ad_group" and parent_id and not campaign_id: + campaign_id = str(parent_id) for c in _campaigns(config, account, customer): cid = str(c.get("Id")) if entity_type == "campaign": if cid == entity_id: return {"entity": c, "campaign": c} continue - if entity_type == "ad_group" and parent_id and cid != str(parent_id): + if campaign_id and cid != str(campaign_id): continue for g in _ad_groups(config, account, customer, cid): gid = str(g.get("Id")) @@ -114,7 +125,7 @@ def draft_microsoft_status( ) -> dict: """Draft pausing or enabling a campaign, ad group, keyword or ad.""" operation = "microsoft_set_status" - blocked = _guard(operation, config) + blocked = _blocked(operation, config) if blocked: return blocked entity_type = (entity_type or "").strip().lower() @@ -152,23 +163,20 @@ def draft_microsoft_status( warnings.append("Pausing the campaign stops every ad in it.") changes = { + "entity_name": _label(found, entity_type), + "campaign_name": found["campaign"].get("Name") if entity_type != "campaign" else None, + "ad_group_name": found["ad_group"].get("Name") if found.get("ad_group") and entity_type != "ad_group" else None, + "current_status": current, + "target_status": target, + } + payload = { "ad_account_id": account, "customer_id": customer, - "name": _label(found, entity_type), - "entity_name": _label(found, entity_type), "campaign_id": str(found["campaign"].get("Id")), - "campaign_name": found["campaign"].get("Name"), - "ad_group_id": str(found["ad_group"].get("Id")) if found.get("ad_group") else None, - "ad_group_name": found["ad_group"].get("Name") if found.get("ad_group") else None, + "ad_group_id": str(found["ad_group"].get("Id")) if found.get("ad_group") else "", "ad_type": entity.get("Type") if entity_type == "ad" else None, - "current_status": current, - "target_status": target, } - return _store( - {"operation": operation, "entity_type": entity_type, "entity_id": entity_id, - "customer_id": account, "changes": changes}, - warnings=warnings, - ) + return store_plan_preview(operation, entity_type, entity_id, account, changes, payload, warnings=warnings) def draft_microsoft_campaign_budget( @@ -178,7 +186,7 @@ def draft_microsoft_campaign_budget( from adloop.safety.guards import SafetyViolation, check_budget_cap operation = "microsoft_update_campaign_budget" - blocked = _guard(operation, config) + blocked = _blocked(operation, config) if blocked: return blocked errors = [] @@ -223,31 +231,20 @@ def draft_microsoft_campaign_budget( f"Microsoft can spend up to 30.4 × the daily budget in a month: about " f"{round(amount * 30.4, 2)} {meta['currency']}." ) - return _store( + return store_plan_preview( + operation, "campaign", campaign_id, account, { - "operation": operation, - "entity_type": "campaign", - "entity_id": campaign_id, - "customer_id": account, - "changes": { - "ad_account_id": account, - "customer_id": customer, - "entity_name": campaign.get("Name"), - "campaign_name": campaign.get("Name"), - "campaign_status": campaign.get("Status"), - "current_daily_budget": current, - "new_daily_budget": amount, - "currency": meta["currency"], - }, + "entity_name": campaign.get("Name"), + "campaign_status": campaign.get("Status"), + "current_daily_budget": current, + "new_daily_budget": amount, + "currency": meta["currency"], }, + {"ad_account_id": account, "customer_id": customer}, warnings=warnings, ) -def is_microsoft_plan(plan: ChangePlan) -> bool: - return str(plan.operation or "").startswith(OPERATION_PREFIX) - - def preflight(config: AdLoopConfig, plan: ChangePlan) -> dict: """Re-read the target and re-check the gates; sends nothing.""" from adloop.microsoft_ads import manage @@ -255,15 +252,16 @@ def preflight(config: AdLoopConfig, plan: ChangePlan) -> dict: if plan.operation in manage.OPERATIONS: return manage.preflight(config, plan) - changes = plan.changes or {} + changes = plan.apply_payload() account = changes.get("ad_account_id") or plan.customer_id customer = changes.get("customer_id") or "" parent = changes.get("ad_group_id") if plan.entity_type in ("keyword", "ad") else "" - found = find_entity(config, account, customer, plan.entity_type, plan.entity_id, parent_id=parent or "") + found = find_entity(config, account, customer, plan.entity_type, plan.entity_id, parent_id=parent or "", + campaign_id=changes.get("campaign_id") or "") if not found: raise ValueError(f"{plan.entity_type} '{plan.entity_id}' no longer exists.") entity = found["entity"] - checks: dict[str, Any] = {"ad_account_id": account, "entity": changes.get("name") or entity.get("Name")} + checks: dict[str, Any] = {"ad_account_id": account, "entity": changes.get("entity_name") or entity.get("Name")} if plan.operation == "microsoft_set_status": now = entity.get("Status") if now != changes.get("current_status"): @@ -307,7 +305,7 @@ def apply_plan(config: AdLoopConfig, plan: ChangePlan) -> dict: preflight(config, plan) if plan.operation in manage.OPERATIONS: return manage.apply_plan(config, plan) - changes = plan.changes or {} + changes = plan.apply_payload() account = changes.get("ad_account_id") or plan.customer_id customer = changes.get("customer_id") or "" kwargs = {"account_id": account, "customer_id": customer, "method": "PUT", "mutation": True} @@ -321,7 +319,7 @@ def apply_plan(config: AdLoopConfig, plan: ChangePlan) -> dict: ) _raise_partial(payload, "budget change") return {"entity_type": "campaign", "entity_id": plan.entity_id, - "campaign_name": changes.get("campaign_name"), + "campaign_name": changes.get("entity_name"), "daily_budget": changes["new_daily_budget"], "currency": changes.get("currency")} if plan.operation == "microsoft_set_status": @@ -342,6 +340,6 @@ def apply_plan(config: AdLoopConfig, plan: ChangePlan) -> dict: path = "Ads" payload = campaign_request(config, path, body, **kwargs) _raise_partial(payload, "status change") - return {"entity_type": etype, "entity_id": eid, "name": changes.get("name"), "status": status} + return {"entity_type": etype, "entity_id": eid, "name": changes.get("entity_name"), "status": status} raise ValueError(f"Unknown Microsoft operation: {plan.operation}") diff --git a/src/adloop/oauth_redirect.py b/src/adloop/oauth_redirect.py index 6fbc6a00..5091a9ba 100644 --- a/src/adloop/oauth_redirect.py +++ b/src/adloop/oauth_redirect.py @@ -1,13 +1,17 @@ -"""One-shot localhost listener for OAuth redirects (sign-in commands). +"""Localhost listener for OAuth redirects (sign-in commands). ``adloop microsoft-login`` opens the provider's sign-in page in the browser; the provider then redirects to -``http://localhost:/?code=...&state=...``. This serves that one -request and returns its query parameters. - -Hardened against a stuck sign-in: the overall deadline uses a monotonic -clock, and every socket read is bounded, so an accepted connection that -never sends a request cannot hold the command open. +``http://localhost:/?code=...&state=...``. The listener binds a +free port first (Entra, like RFC 8252 asks, ignores the port of a localhost +redirect URI), so the redirect URI is only known once it is listening: +:class:`RedirectListener` binds, then names its ``redirect_uri``, then waits. + +It serves requests until one carries the sign-in's ``state`` (a stray or +forged request is answered and ignored), and is hardened against a stuck +sign-in: the overall deadline uses a monotonic clock, and every socket read +is bounded, so an accepted connection that never sends a request cannot hold +the command open. """ from __future__ import annotations @@ -71,65 +75,91 @@ def close(self) -> None: return None -def is_local_redirect(redirect_uri: str) -> bool: - parts = urlsplit(redirect_uri) - return parts.scheme == "http" and parts.hostname in ("localhost", "127.0.0.1") - +class RedirectListener: + """One sign-in's redirect listener on localhost; ``port=0`` picks a free port.""" + + def __init__(self, *, host: str = "localhost", path: str = "/callback", port: int = 0, provider: str = "the"): + from http.server import BaseHTTPRequestHandler, HTTPServer + + self.path = path or "/" + self._deadline = 0.0 + self._state: str | None = None + self.captured: dict = {} + listener = self + page = ( + "

AdLoop received the " + f"{provider} sign-in.

You can close this tab and return to the terminal.

" + ).encode() + stray = ( + b"

This is not the sign-in AdLoop is waiting " + b"for.

Finish the sign-in in the tab AdLoop opened.

" + ) + + class Handler(BaseHTTPRequestHandler): + def setup(self): + super().setup() + # The whole request must arrive within the connection's budget + # and the sign-in deadline, however slowly it trickles in. + self.rfile = _DeadlineReader( + self.connection, min(listener._deadline, time.monotonic() + _PER_CONNECTION_SECONDS)) + + def do_GET(self): # noqa: N802 (http.server naming) + here = urlsplit(self.path) + if (here.path or "/") != listener.path: + self.send_response(404) + self.end_headers() + return + query = dict(parse_qsl(here.query)) + ours = listener._state is None or query.get("state") == listener._state + self.send_response(200 if ours else 400) + self.send_header("Content-Type", "text/html; charset=utf-8") + self.end_headers() + self.wfile.write(page if ours else stray) + if ours: + listener.captured.update(query) -def listen_once(redirect_uri: str, timeout: float, *, provider: str = "the") -> dict: - """Serve the redirect URI on localhost until the browser arrives; return its query.""" - from http.server import BaseHTTPRequestHandler, HTTPServer + def log_message(self, *_args): + return - parts = urlsplit(redirect_uri) - expected_path = parts.path or "/" - captured: dict = {} - page = ( - "

AdLoop received the " - f"{provider} sign-in.

You can close this tab and return to the terminal.

" - ).encode() - - class Handler(BaseHTTPRequestHandler): - def setup(self): - super().setup() - # The whole request must arrive within the connection's budget - # and the sign-in deadline, however slowly it trickles in. - self.rfile = _DeadlineReader( - self.connection, min(deadline, time.monotonic() + _PER_CONNECTION_SECONDS)) - - def do_GET(self): # noqa: N802 (http.server naming) - here = urlsplit(self.path) - if (here.path or "/") != expected_path: - self.send_response(404) - self.end_headers() + class Server(HTTPServer): + def handle_error(self, request, client_address): # noqa: D401 — silence timeouts return - captured.update(dict(parse_qsl(here.query))) - self.send_response(200) - self.send_header("Content-Type", "text/html; charset=utf-8") - self.end_headers() - self.wfile.write(page) - - def log_message(self, *_args): - return - - # An accepted connection that never sends a request must not hold the - # sign-in past its deadline: every socket read is bounded too. - Handler.timeout = max(0.1, min(5.0, timeout)) - - class Server(HTTPServer): - def handle_error(self, request, client_address): # noqa: D401 — silence timeouts - return - - server = Server((parts.hostname or "127.0.0.1", parts.port or 80), Handler) - deadline = time.monotonic() + timeout - try: - while not captured: - remaining = deadline - time.monotonic() + + self._handler = Handler + self._server = Server((host or "127.0.0.1", port), Handler) + self.port = self._server.server_address[1] + self.redirect_uri = f"http://{host}:{self.port}{self.path}" + + def wait(self, timeout: float, *, state: str | None = None) -> dict: + """Serve until a request with ``state`` (any, when None) arrives; return its query.""" + self._state = state + self._deadline = time.monotonic() + timeout + # An accepted connection that never sends a request must not hold the + # sign-in past its deadline: every socket read is bounded too. + self._handler.timeout = max(0.1, min(5.0, timeout)) + while not self.captured: + remaining = self._deadline - time.monotonic() if remaining <= 0: break - server.timeout = min(1.0, remaining) - server.handle_request() - finally: - server.server_close() - if not captured: - raise RedirectTimeout("No sign-in arrived before the timeout.") - return captured + self._server.timeout = min(1.0, remaining) + self._server.handle_request() + if not self.captured: + raise RedirectTimeout("No sign-in arrived before the timeout.") + return self.captured + + def close(self) -> None: + self._server.server_close() + + def __enter__(self) -> RedirectListener: + return self + + def __exit__(self, *_exc) -> None: + self.close() + + +def listen_once(redirect_uri: str, timeout: float, *, provider: str = "the", state: str | None = None) -> dict: + """Serve a fixed redirect URI until the browser arrives; return its query.""" + parts = urlsplit(redirect_uri) + with RedirectListener(host=parts.hostname or "127.0.0.1", path=parts.path or "/", + port=parts.port or 80, provider=provider) as listener: + return listener.wait(timeout, state=state) diff --git a/src/adloop/rules/adloop.md b/src/adloop/rules/adloop.md index 3f0adc6b..a1ad6274 100644 --- a/src/adloop/rules/adloop.md +++ b/src/adloop/rules/adloop.md @@ -267,7 +267,7 @@ Reddit is a second ad platform with its own connection (own OAuth app, no develo ### Microsoft Advertising Tools -Microsoft Advertising (Bing, Yahoo, AOL, DuckDuckGo search ads) through the REST API v13. Toolset `microsoft_ads`; needs `microsoft_ads.developer_token`, `microsoft_ads.client_id` (an Entra app with public client flows and the msads.manage permission) and a one-time `adloop microsoft-login` (browser sign-in on `http://localhost:8080/callback`; sign in with the user that has access to the ad accounts. Directories with security defaults block the device-code flow with sign-in error 530035, so `--device-code` is only a fallback). `customer_id` is the manager account, `ad_account_id` the default ad account; `list_microsoft_ads_accounts` shows both. +Microsoft Advertising (Bing, Yahoo, AOL, DuckDuckGo search ads) through the REST API v13. Toolset `microsoft_ads`; needs `microsoft_ads.developer_token`, `microsoft_ads.client_id` (an Entra app with public client flows and the msads.manage permission) and a one-time `adloop microsoft-login` (browser sign-in; the Entra app registers `http://localhost/callback` and the sign-in listens on a free port of it, since Entra ignores the port of localhost redirects. Sign in with the user that has access to the ad accounts. Directories with security defaults block the device-code flow with sign-in error 530035, so `--device-code` is only a fallback). Users who sign in to Microsoft Advertising with Google are not supported yet: an `MICROSOFT_ADS_NOT_AN_ACCOUNT_USER` error after a working sign-in means the Microsoft identity is not a user of the ad account; invite a Microsoft account or work (Entra) user and sign in as that user. `customer_id` is the manager account, `ad_account_id` the default ad account; `list_microsoft_ads_accounts` shows both. | Tool | When to Use | Key Parameters | |------|-------------|----------------| @@ -302,10 +302,13 @@ Microsoft Advertising (Bing, Yahoo, AOL, DuckDuckGo search ads) through the REST - **Location intent matters for local businesses.** `PeopleInOrSearchingForOrViewingPages` (Microsoft's default) also reaches people elsewhere searching about the area. `get_microsoft_location_performance` shows how much spend that "location of interest" traffic took. - **Monthly spend:** Microsoft may spend up to 30.4 × the daily budget in a month; the budget preview says so. - **Writes** go through draft → preview → `confirm_and_apply`. Microsoft has no validate-only mode: the dry run re-reads the target, refuses if the budget or status changed since the draft or the campaign moved to a shared budget, and re-checks the cap. The real apply runs the same checks again right before sending, so a change made in Microsoft Advertising in between is refused, not overwritten: draft again. Updates send only the changed field. -- **Management rules** mirror Google Ads: broad match is refused on ManualCpc / EnhancedCpc campaigns, moving to manual bidding is refused while active broad keywords exist, new campaigns need languages and locations (default PeopleIn), new RSAs and campaigns are paused, while new keywords and ad groups are created Active as in Google Ads (the preview's `status_on_create` says so, and keywords in a live ad group serve as soon as they are applied), keyword and ad group bid raises are capped by `max_bid_increase_pct` (including a keyword falling back to the ad group bid), a first ad schedule needs a double confirmation. Replacing a schedule window deletes the old window before adding the new one when they overlap; the preview warns when that leaves the campaign briefly unscheduled. Negative keywords go in shared lists by default; every negative draft names active keywords it would block. +- **Management rules** mirror Google Ads: broad match is refused unless the campaign uses conversion-based bidding (MaxConversions, MaxConversionValue, or a target CPA/ROAS; Maximize Clicks does not count), moving to any other strategy is refused while active broad keywords exist, MaxConversions is refused (at the draft and the dry run) while the account has no active conversion goal, because Microsoft refuses it then, new campaigns need languages (not `All`) and locations (default PeopleIn), new RSAs and campaigns are paused, while new keywords and ad groups are created Active as in Google Ads (the preview's `status_on_create` says so, and keywords in a live ad group serve as soon as they are applied), keyword and ad group bid raises are capped by `max_bid_increase_pct` (including a keyword falling back to the ad group bid), a first ad schedule needs a double confirmation. Replacing a schedule window deletes the old window before adding the new one when they overlap; the preview warns when that leaves the campaign briefly unscheduled. Negative keywords go in shared lists by default; every negative draft names active keywords it would block. - **Multi-step applies** (a campaign then its targeting, a list then its attachments, extensions then their links) end with `PARTIAL_APPLY` when a later step fails, or when Microsoft creates some items of a batch and refuses others: `created` lists the IDs that exist, and the plan is retired so nothing is created twice. Check the account, then draft only what is missing. - **Image extensions** (`draft_microsoft_image_extension`): JPEG, PNG or non-animated GIF, at most 5 MB, **1.91:1** (e.g. 1200x628), at least 703x368, at most 2592 wide and 2048 high; the draft refuses anything else and says how to crop it. Ask the user for alt text that describes the photo. Microsoft's help allows 25 image extensions per account, campaign or ad group, its API reference says 6: the draft warns above 6 and refuses above 25. `display_text` adds the multi-image layout, which needs at least five images in four extensions. **Caution:** image extensions can take search ads beyond Bing results: Microsoft's audience ads guide says search ads are extended to native placements on the Microsoft Audience Network (Outlook, MSN) with their image extensions, so check the ad groups' Audience Network setting with `get_microsoft_ad_groups` when the client wants search only. Images without a public URL go through `upload_images` first. - Reports are built asynchronously and take a few seconds; long date ranges at keyword or search-term level take longer. +- **Rate limits:** Microsoft counts calls per customer in a sliding 60-second window (code 117) and caps concurrent reports (code 207). Both come back as `MICROSOFT_ADS_RATE_LIMITED` with `retry_after` 60: wait that long, never retry in a loop. +- **Removing a criterion** (`remove_microsoft_entity`, `campaign_criterion`) reads it first and names it; the last targeted location is refused, because the campaign would serve everywhere. Replace locations with `update_microsoft_campaign_targeting` instead. +- **Audience Network:** an ad group without its own `audience_ads_bid_adjustment` inherits the campaign's; -100 switches it off. `get_microsoft_ad_groups` shows the effective setting and where it is set (`audience_network`). - Search terms with clicks and no conversions are candidates, not verdicts: calls from Microsoft ads convert outside its view unless call tracking feeds back. - **Conversions** come from Microsoft's `ConversionsQualified` columns (the old `Conversions` columns are deprecated and read 0 in keyword and search-term reports); conversion rate and CPA are computed from them. A UET tag is required only by URL, duration, pages-per-visit and event goals: offline-import goals need none, and an unverified tag that no active goal uses is a loose end (warn), not a broken setup. diff --git a/src/adloop/server.py b/src/adloop/server.py index 20fb0440..27801ba4 100644 --- a/src/adloop/server.py +++ b/src/adloop/server.py @@ -533,6 +533,16 @@ def _microsoft_ads_structured_error(exc: Exception) -> dict | None: "microsoft_ads.developer_token." ), "missing_client": "Set microsoft_ads.client_id to the Entra app id, then run `adloop microsoft-login`.", + "not_an_account_user": ( + "Invite a Microsoft account or a work (Entra) user to the ad account in Microsoft " + "Advertising, then run `adloop microsoft-login` as that user. Signing in with Google " + "is not supported yet." + ), + "google_identity": ( + "This account's users sign in with Google, which AdLoop does not support yet. Invite a " + "Microsoft account or a work (Entra) user to the ad account, then run " + "`adloop microsoft-login` as that user." + ), } return { "error": str(exc), @@ -547,7 +557,10 @@ def _microsoft_ads_structured_error(exc: Exception) -> dict | None: if exc.status == 429: return { "error": str(exc), - "hint": "Wait for the reset before calling again; do not retry in a loop.", + "hint": ( + f"Wait {exc.retry_after or 60} seconds before calling Microsoft Advertising again; " + "do not retry in a loop." + ), "auth_error": "MICROSOFT_ADS_RATE_LIMITED", "retry_after": exc.retry_after, } @@ -7294,7 +7307,7 @@ def get_microsoft_keywords(ad_account_id: str = "", campaign_id: str = "", ad_gr """List Microsoft Advertising keywords with match type, bid, status and editorial review, plus the status of their ad group and campaign. Insights flag disapproved keywords and active broad-match keywords in - manual-bid campaigns. + campaigns without conversion-based bidding (manual bids or Maximize Clicks). Args: ad_account_id: Microsoft ad account id. Empty uses the config default. @@ -7599,8 +7612,10 @@ def update_microsoft_campaign( Bid strategies: ManualCpc, EnhancedCpc, MaxClicks, MaxConversions (with an optional target_cpa; TargetCpa is accepted and becomes MaxConversions, - as Microsoft now does). Moving to manual bidding is refused while the - campaign has active broad-match keywords. The daily budget has its own + as Microsoft now does). Moving to a strategy that is not conversion-based + (manual bids or MaxClicks) is refused while the campaign has active + broad-match keywords, and moving to MaxConversions is refused while the + account has no active conversion goal. The daily budget has its own tool, update_microsoft_campaign_budget. The returned plan_id is applied with confirm_and_apply, which refuses if a changed setting was edited after the preview. @@ -7677,8 +7692,10 @@ def draft_microsoft_campaign( """Draft a new Microsoft Advertising Search campaign, created PAUSED with its locations (preview only). Requires a daily budget (capped by max_daily_budget), languages and - included locations. Defaults to MaxConversions and PeopleIn; warns when - no conversion goal counts toward Conversions. The apply creates the + included locations (languages=["All"] is refused). Defaults to + MaxConversions and PeopleIn; MaxConversions is refused while no active + conversion goal counts toward Conversions, because Microsoft refuses the + campaign then (pass MaxClicks, EnhancedCpc or ManualCpc). The apply creates the campaign, then its location criteria, and names what was created if the second step fails. The returned plan_id is applied with confirm_and_apply. @@ -7718,7 +7735,8 @@ def draft_microsoft_ad_group( The ad group is created active but serves only once one of its ads (new ads are paused) is enabled. Manual-bid campaigns need cpc_bid; broad - match is refused unless the campaign uses automated bidding. network + match is refused unless the campaign uses conversion-based bidding + (MaxConversions, MaxConversionValue or a target CPA/ROAS). network OwnedAndOperatedOnly (default) keeps ads off syndicated partner sites. The returned plan_id is applied with confirm_and_apply. @@ -7773,7 +7791,8 @@ def draft_microsoft_keywords(ad_account_id: str = "", ad_group_id: str = "", key """Draft adding keywords to a Microsoft Advertising ad group (preview only). Keywords already in the ad group are skipped; broad match is refused - unless the campaign uses automated bidding. The returned plan_id is + unless the campaign uses conversion-based bidding (MaxConversions, + MaxConversionValue or a target CPA/ROAS). The returned plan_id is applied with confirm_and_apply. Args: @@ -8129,7 +8148,10 @@ def remove_microsoft_entity(ad_account_id: str = "", entity_type: str = "", enti Removes a campaign, ad group, ad or keyword by id, or (by the remove_id the read tools return) a direct negative keyword, a negative list item, a location or schedule criterion, or an extension link (account, - campaign or ad group, image extensions included). Pausing keeps + campaign or ad group, image extensions included). A criterion is read + and named first; the last targeted location is refused (the campaign + would serve everywhere; update_microsoft_campaign_targeting replaces + the whole list). Pausing keeps history and can be undone. The returned plan_id is applied with confirm_and_apply. diff --git a/tests/test_microsoft_ads.py b/tests/test_microsoft_ads.py index 75ce6bd4..1d2be17d 100644 --- a/tests/test_microsoft_ads.py +++ b/tests/test_microsoft_ads.py @@ -28,7 +28,8 @@ def _fresh_state(tmp_path): global _LOG_FILE _LOG_FILE = str(tmp_path / "audit.log") preview_store.set_plan_store(InMemoryPlanStore()) - read.reset_account_cache() + read._account_cache.clear() + read._targets_query["refused"] = False auth.reset_credentials_cache() yield preview_store.set_plan_store(InMemoryPlanStore()) @@ -197,6 +198,9 @@ def handle(config, service, path, body=None, *, method="POST", account_id="", cu if key == ("campaign", "Campaigns/QueryByAccountId"): return _CAMPAIGNS if key == ("campaign", "CampaignCriterions/QueryByIds"): + if body["CriterionType"] == "Targets": + return {"CampaignCriterions": [c for (cid, _kind), rows in _CRITERIONS.items() + if cid == body["CampaignId"] for c in rows]} return {"CampaignCriterions": _CRITERIONS.get((body["CampaignId"], body["CriterionType"]), [])} if key == ("campaign", "AdGroups/QueryByCampaignId"): return {"AdGroups": _AD_GROUPS.get(body["CampaignId"], [])} @@ -381,12 +385,41 @@ def test_operation_errors_are_reported(self, creds): assert "CampaignServiceInvalidAccountId: The account ID is invalid." in str(err.value) assert "trk-1" in str(err.value) and "1100" in err.value.codes - def test_throttling_waits_briefly(self, creds): - throttled = _Resp(400, {"Errors": [{"Code": 117, "ErrorCode": "CallRateExceeded", "Message": "slow down"}]}, + @pytest.mark.parametrize(("code", "name", "service"), [ + (117, "CallRateExceeded", "customer"), (207, "ConcurrentRequestOverLimit", "reporting")]) + def test_throttling_raises_at_once_with_a_minute_to_wait(self, creds, code, name, service): + # Microsoft counts calls in a sliding 60-second window: a retry after 5 s only extends it. + throttled = _Resp(400, {"Errors": [{"Code": code, "ErrorCode": name, "Message": "slow down"}]}, headers={"Retry-After": "2"}) - with patch("requests.request", side_effect=[throttled, _Resp(200, {"ok": 1})]), patch("time.sleep") as sleep: - assert client.ms_request(_config(), "customer", "User/Query", {}) == {"ok": 1} - sleep.assert_called_once_with(2) + with patch("requests.request", side_effect=[throttled]) as sent, patch("time.sleep") as sleep, \ + pytest.raises(MicrosoftAdsApiError) as err: + client.ms_request(_config(), service, "User/Query", {}) + assert sent.call_count == 1 and not sleep.called + assert err.value.status == 429 and err.value.retry_after == 60 + from adloop.server import _structured_error + + parsed = _structured_error("get_microsoft_performance", err.value) + assert parsed["auth_error"] == "MICROSOFT_ADS_RATE_LIMITED" and parsed["retry_after"] == 60 + assert "60 seconds" in parsed["hint"] + + def test_invalid_credentials_after_a_refresh_explain_the_identity(self, creds): + # A Google-identity user signs in with the Microsoft account of the same + # email: the sign-in works, and every call answers a bare 105. + bare = _Resp(401, {"Errors": [{"Code": 105, "ErrorCode": "InvalidCredentials", + "Message": "Authentication failed."}]}) + with patch("requests.request", side_effect=[bare, bare]), pytest.raises(MicrosoftAdsAuthError) as err: + client.ms_request(_config(), "customer", "User/Query", {}) + assert err.value.error_code == "not_an_account_user" and creds.refreshes == 1 + assert "not a user of the ad account" in str(err.value) and "Google" in str(err.value) + from adloop.server import _structured_error + + assert "Microsoft account or a work (Entra) user" in _structured_error("health_check", err.value)["hint"] + + def test_a_google_identity_fault_is_named(self, creds): + fault = _Resp(400, {"Errors": [{"Code": 0, "ErrorCode": "GoogleAccountIsRequired", "Message": "x"}]}) + with patch("requests.request", side_effect=[fault]), pytest.raises(MicrosoftAdsAuthError) as err: + client.ms_request(_config(), "customer", "User/Query", {}) + assert err.value.error_code == "google_identity" and creds.refreshes == 0 def test_report_runner_polls_and_parses(self, creds): responses = iter([ @@ -573,9 +606,14 @@ def test_pause_keyword_finds_its_parents(self): preview = write.draft_microsoft_status(_config(), action="pause", entity_type="keyword", entity_id="101") assert preview["platform"] == "microsoft" changes = preview["changes"] - assert changes["name"] == "drain cleaning [Phrase]" - assert changes["ad_group_id"] == "11" and changes["campaign_id"] == "500100200" + assert changes["entity_name"] == "drain cleaning [Phrase]" assert changes["current_status"] == "Active" and changes["target_status"] == "Paused" + assert changes["ad_group_name"] == "Drains" and changes["campaign_name"] == "Acme Plumbing - Search" + # The ids the apply needs stay out of what the person approves. + plan = preview_store.get_plan(preview["plan_id"]) + assert not {"ad_group_id", "campaign_id", "ad_account_id", "customer_id"} & set(changes) + assert plan.apply_only_payload["ad_group_id"] == "11" + assert plan.apply_only_payload["campaign_id"] == "500100200" def test_enable_warns_about_paused_parent(self): _, _, ctx = _fake_api() @@ -901,7 +939,7 @@ def test_budget_blocked_after_the_dry_run_cannot_apply(self): assert result["status"] == "BLOCKED" and not [c for c in calls if c[3] == "PUT"] def test_status_dialog_shows_the_target_status(self): - # Finding 2: the requested status must not hide behind "more fields". + # The question and the status change lead; no ids or duplicate names follow. from adloop.safety.approval import confirmation_message _, _, ctx = _fake_api() @@ -909,8 +947,9 @@ def test_status_dialog_shows_the_target_status(self): preview = write.draft_microsoft_status(_config(), action="pause", entity_type="keyword", entity_id="101") message = confirmation_message(preview_store.get_plan(preview["plan_id"])) lines = message.splitlines() - assert "- target status: Paused" in lines and "- current status: Active" in lines - assert "more fields" not in message + assert lines[0] == 'AdLoop: set status "drain cleaning [Phrase]" in Microsoft Advertising?' + assert lines[1].startswith(f"Account {ACCOUNT} · Active → Paused") + assert "more fields" not in message and " id: " not in message assert sum(1 for l in lines if "drain cleaning [Phrase]" in l) == 1 # no duplicate name line def test_token_errors_never_echo_credentials(self): @@ -936,27 +975,29 @@ def test_authorization_code_with_pkce_end_to_end(self, tmp_path): opened: list[str] = [] - def listen(uri): - assert uri == "http://localhost:8080/callback" + def listen(uri, state): + assert uri == "http://localhost:51234/callback" query = parse_qs(urlsplit(opened[0]).query) - return {"code": "auth-code-1", "state": query["state"][0]} + assert state == query["state"][0] + return {"code": "auth-code-1", "state": state} with patch("adloop.microsoft_ads.auth._post_form", return_value=(200, { "access_token": "at", "refresh_token": "rt-new", "expires_in": 3600, "scope": auth.SCOPE, })) as post: path = auth.browser_login(self._cfg(tmp_path), login_hint="ads@contoso.onmicrosoft.com", - say=lambda _m: None, open_browser=opened.append, listen=listen) + say=lambda _m: None, open_browser=opened.append, listen=listen, + redirect_uri="http://localhost:51234/callback") url = urlsplit(opened[0]) query = parse_qs(url.query) assert url.netloc == "login.microsoftonline.com" and url.path == "/common/oauth2/v2.0/authorize" assert query["client_id"] == ["app-client-id"] and query["response_type"] == ["code"] - assert query["redirect_uri"] == ["http://localhost:8080/callback"] + assert query["redirect_uri"] == ["http://localhost:51234/callback"] assert query["scope"] == [auth.SCOPE] and query["code_challenge_method"] == ["S256"] assert query["login_hint"] == ["ads@contoso.onmicrosoft.com"] and query["prompt"] == ["select_account"] form = post.call_args.args[1] assert post.call_args.args[0].endswith("/common/oauth2/v2.0/token") assert form["grant_type"] == "authorization_code" and form["code"] == "auth-code-1" - assert form["redirect_uri"] == "http://localhost:8080/callback" + assert form["redirect_uri"] == "http://localhost:51234/callback" # The verifier sent at the token step matches the challenge sent at authorize. challenge = base64.urlsafe_b64encode(hashlib.sha256(form["code_verifier"].encode()).digest()).decode().rstrip("=") assert challenge == query["code_challenge"][0] @@ -966,19 +1007,17 @@ def listen(uri): def test_state_mismatch_and_provider_errors(self, tmp_path): with patch("adloop.microsoft_ads.auth._post_form") as post, pytest.raises(MicrosoftAdsAuthError) as err: auth.browser_login(self._cfg(tmp_path), say=lambda _m: None, open_browser=lambda _u: None, - listen=lambda _u: {"code": "c", "state": "forged"}) + listen=lambda _u, _s: {"code": "c", "state": "forged"}) assert err.value.error_code == "state_mismatch" and not post.called with pytest.raises(MicrosoftAdsAuthError) as err: auth.browser_login(self._cfg(tmp_path), say=lambda _m: None, open_browser=lambda _u: None, - listen=lambda _u: {"error": "access_denied", + listen=lambda _u, _s: {"error": "access_denied", "error_description": "AADSTS530035: blocked by security defaults"}) assert err.value.error_code == "access_denied" and "530035" in str(err.value) def test_refused_code_redacts_it(self, tmp_path): - from urllib.parse import parse_qs, urlsplit - opened: list[str] = [] - listen = lambda _u: {"code": "secret-code-123", "state": parse_qs(urlsplit(opened[0]).query)["state"][0]} # noqa: E731 + listen = lambda _u, state: {"code": "secret-code-123", "state": state} # noqa: E731 echo = {"error": "invalid_grant", "error_description": "code secret-code-123 was already redeemed"} with patch("adloop.microsoft_ads.auth._post_form", return_value=(400, echo)), \ pytest.raises(MicrosoftAdsAuthError) as err: @@ -1011,6 +1050,51 @@ def test_real_listener_receives_the_redirect(self, tmp_path): worker.join(timeout=10) assert got == {"code": "abc", "state": "xyz"} and "Microsoft Advertising sign-in" in response.text + def test_real_sign_in_listens_on_a_free_port_until_the_state_matches(self, tmp_path): + import threading + from urllib.parse import parse_qs, urlsplit + + import requests + + opened: list[str] = [] + ready = threading.Event() + + def open_browser(url): + opened.append(url) + ready.set() + + result: dict = {} + with patch("adloop.microsoft_ads.auth._post_form", return_value=(200, { + "access_token": "at", "refresh_token": "rt-new", "expires_in": 3600})) as post: + worker = threading.Thread(target=lambda: result.update(path=auth.browser_login( + self._cfg(tmp_path), say=lambda _m: None, open_browser=open_browser))) + worker.start() + assert ready.wait(10) + query = parse_qs(urlsplit(opened[0]).query) + redirect = query["redirect_uri"][0] + port = urlsplit(redirect).port + assert redirect == f"http://localhost:{port}/callback" and port not in (None, 8080) + local = redirect.replace("localhost", "127.0.0.1") + stray = requests.get(f"{local}?code=forged&state=other", timeout=5) + real = requests.get(f"{local}?code=good&state={query['state'][0]}", timeout=5) + worker.join(timeout=10) + assert stray.status_code == 400 and real.status_code == 200 + form = post.call_args.args[1] + assert form["code"] == "good" and form["redirect_uri"] == redirect + assert json.loads(result["path"].read_text())["refresh_token"] == "rt-new" + + def test_the_token_file_is_never_written_through_a_planted_file(self, tmp_path): + target = tmp_path / "ms_token.json" + planted = tmp_path / "elsewhere.json" + planted.write_text("{}") + # A stale or planted temp file at the old fixed name is left alone. + (tmp_path / "ms_token.json.tmp").symlink_to(planted) + auth.write_token_file(target, {"refresh_token": "rt"}) + assert json.loads(target.read_text()) == {"refresh_token": "rt"} + assert planted.read_text() == "{}" + assert stat.S_IMODE(os.stat(target).st_mode) == 0o600 + assert not [f for f in tmp_path.iterdir() if f.name.startswith(".ms_token.json.")] + def test_cli_defaults_to_the_browser_and_keeps_device_code(self, tmp_path, monkeypatch, capsys): import adloop diff --git a/tests/test_microsoft_ads_manage.py b/tests/test_microsoft_ads_manage.py index 332d19c3..f3301093 100644 --- a/tests/test_microsoft_ads_manage.py +++ b/tests/test_microsoft_ads_manage.py @@ -90,6 +90,8 @@ def __init__(self): self.in_store_pilot = True self.calls: list[dict] = [] self.fail: dict[tuple, Exception] = {} + # Whether Microsoft refuses one "Targets" query for every criterion type. + self.refuse_targets_query = False self._next = 5000 def _id(self) -> int: @@ -139,9 +141,10 @@ def __call__(self, config, service, path, body=None, *, method="POST", account_i return {"Campaigns": out} if path == "CampaignCriterions/QueryByIds": kind = body["CriterionType"] - wanted = {"Location": "Location", "LocationIntent": "LocationIntent", "DayTime": "DayTime", "Radius": "Radius"}[kind] + if kind == "Targets" and self.refuse_targets_query: + raise MicrosoftAdsApiError("InvalidCriterionType", status=400, codes=["InvalidCriterionType"]) return {"CampaignCriterions": [copy.deepcopy(c) for c in self.criteria.get(str(body["CampaignId"]), []) - if c["Criterion"]["Type"].replace("Criterion", "") == wanted]} + if kind == "Targets" or c["Criterion"]["Type"].replace("Criterion", "") == kind]} if path == "AdGroups/QueryByCampaignId": return {"AdGroups": [self._pub(g) for g in self.ad_groups.values() if g["_campaign"] == str(body["CampaignId"])]} if path == "Keywords/QueryByAdGroupId": @@ -379,7 +382,8 @@ def api(): @pytest.fixture(autouse=True) def _fresh(monkeypatch): preview_store.set_plan_store(InMemoryPlanStore()) - read.reset_account_cache() + read._account_cache.clear() + read._targets_query["refused"] = False read._GEO_CACHE.clear() monkeypatch.setattr("adloop.ads.write._validate_urls", lambda urls, timeout=10: ({u: None for u in urls}, {})) yield @@ -404,6 +408,23 @@ def _apply(config, preview): return result["result"] +def _payload(preview) -> dict: + """What the dry run and the apply read: the plan's changes plus its apply-only payload.""" + return preview_store.get_plan(preview["plan_id"]).apply_payload() + + +def _approval_surfaces(config, preview) -> str: + """Everything a person (or the audit log) sees of a plan: preview, dialog and log entries.""" + from adloop.safety.approval import confirmation_message + + from pathlib import Path + + plan = preview_store.get_plan(preview["plan_id"]) + log = Path(config.safety.log_file) + return (_text(preview) + _text(plan.to_preview()) + confirmation_message(plan) + + (log.read_text() if log.exists() else "")) + + def _last(api, path, method=None): return [c for c in api.calls if c["path"] == path and (method is None or c["method"] == method)][-1] @@ -426,7 +447,7 @@ def test_move_to_max_conversions_with_a_target(self, api, config): def test_strategy_change_warns_and_targetcpa_maps(self, api, config): preview = manage.update_microsoft_campaign(config, campaign_id="600", bidding_strategy="TargetCpa", target_cpa=30) - assert preview["changes"]["update"]["BiddingScheme"]["Type"] == "MaxConversions" + assert _payload(preview)["update"]["BiddingScheme"]["Type"] == "MaxConversions" switched = manage.update_microsoft_campaign(config, campaign_id="600", bidding_strategy="MaxClicks") assert any("learning period" in w for w in switched["warnings"]) @@ -448,11 +469,11 @@ def test_tracking_template_rules(self, api, config): assert "must start with" in _text(manage.update_microsoft_campaign(config, campaign_id=CAMPAIGN, tracking_url_template="track.me")) preview = manage.update_microsoft_campaign(config, campaign_id=CAMPAIGN, tracking_url_template="{lpurl}?src=bing", final_url_suffix="utm_source=bing&utm_medium=cpc") - assert preview["changes"]["update"] == {"Id": CAMPAIGN, "TrackingUrlTemplate": "{lpurl}?src=bing", + assert _payload(preview)["update"] == {"Id": CAMPAIGN, "TrackingUrlTemplate": "{lpurl}?src=bing", "FinalUrlSuffix": "utm_source=bing&utm_medium=cpc"} api.campaigns[CAMPAIGN]["FinalUrlSuffix"] = "utm_source=bing" removal = manage.update_microsoft_campaign(config, campaign_id=CAMPAIGN, final_url_suffix="") - assert removal["changes"]["update"]["FinalUrlSuffix"] == "" and any("removed" in w for w in removal["warnings"]) + assert _payload(removal)["update"]["FinalUrlSuffix"] == "" and any("removed" in w for w in removal["warnings"]) def test_name_rules_and_nothing_to_change(self, api, config): assert "already named" in _text(manage.update_microsoft_campaign(config, campaign_id=CAMPAIGN, name="Brand")) @@ -508,7 +529,7 @@ def test_intent_updates_the_existing_criterion(self, api, config): def test_intent_is_added_when_missing(self, api, config): preview = manage.update_microsoft_campaign_targeting(config, campaign_id="600", location_intent="PeopleIn") - assert preview["changes"]["operations"]["add"][0]["Criterion"]["Type"] == "LocationIntentCriterion" + assert _payload(preview)["operations"]["add"][0]["Criterion"]["Type"] == "LocationIntentCriterion" wide = manage.update_microsoft_campaign_targeting(config, campaign_id="600", location_intent="PeopleInOrSearchingForOrViewingPages") assert any("outside the locations" in w for w in wide["warnings"]) @@ -526,7 +547,7 @@ def test_first_schedule_is_double_confirmed(self, api, config): # Replacing the schedule deletes the old windows; [] clears it. cleared = manage.update_microsoft_campaign_targeting(config, campaign_id=CAMPAIGN, ad_schedule=[]) assert cleared["requires_double_confirm"] is False - ops = cleared["changes"]["operations"] + ops = _payload(cleared)["operations"] assert len(ops["schedule_delete"]) == 5 and ops["schedule_add_first"] == ops["schedule_add_after"] == [] def test_schedule_validation(self, api, config): @@ -580,9 +601,36 @@ def test_guards(self, api, config): assert "location_ids is required" in _text(no_geo) assert "exceeds maximum" in manage.draft_microsoft_campaign(config, name="X", daily_budget=500, languages=["English"], location_ids=["190"])["error"] assert "already exists" in _text(manage.draft_microsoft_campaign(config, name="brand", daily_budget=10, languages=["English"], location_ids=["190"])) + every = manage.draft_microsoft_campaign(config, name="X", daily_budget=10, languages=["All"], location_ids=["190"]) + assert "reaches every language" in _text(every) + manual_target = manage.draft_microsoft_campaign(config, name="X", daily_budget=10, languages=["English"], + location_ids=["190"], bidding_strategy="ManualCpc", target_cpa=30) + assert "target_cpa goes with MaxConversions" in _text(manual_target) + + def test_conversion_bidding_without_a_goal_is_refused_at_the_draft(self, api, config): + # Seen live: the dry run passed, then Microsoft refused the create with + # ConversionGoalCriteriaNotMetForBiddingScheme. + api.goals = [] + refused = manage.draft_microsoft_campaign(config, name="New", daily_budget=10, languages=["English"], + location_ids=["190"]) + assert "plan_id" not in refused and "needs an active conversion goal" in _text(refused) + assert "MaxClicks, EnhancedCpc or ManualCpc" in _text(refused) + clicks = manage.draft_microsoft_campaign(config, name="New", daily_budget=10, languages=["English"], + location_ids=["190"], bidding_strategy="MaxClicks") + assert "plan_id" in clicks + + def test_a_goal_removed_after_the_draft_fails_the_dry_run(self, api, config): + preview = manage.draft_microsoft_campaign(config, name="New", daily_budget=10, languages=["English"], + location_ids=["190"]) api.goals = [] - warn = manage.draft_microsoft_campaign(config, name="New", daily_budget=10, languages=["English"], location_ids=["190"]) - assert any("nothing to optimize" in w for w in warn["warnings"]) + dry = ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=True) + assert dry["status"] == "DRY_RUN_FAILED" and "needs an active conversion goal" in dry["error"] + assert not api.writes() + + def test_the_audience_network_default_is_named(self, api, config): + preview = manage.draft_microsoft_campaign(config, name="New", daily_budget=10, languages=["English"], + location_ids=["190"]) + assert any("Microsoft Audience Network" in w and "-100" in w for w in preview["warnings"]) def test_failed_targeting_step_names_the_created_campaign_and_retry_is_refused(self, api, config): preview = manage.draft_microsoft_campaign(config, name="Half done", daily_budget=10, languages=["English"], location_ids=["190"]) @@ -733,7 +781,7 @@ def test_append_to_list_skips_existing(self, api, config): def test_attach_and_detach(self, api, config): attach = manage.attach_microsoft_negative_keyword_list(config, list_id="900", campaign_ids=[CAMPAIGN, "600"]) - assert attach["changes"]["campaign_ids"] == ["600"] + assert _payload(attach)["campaign_ids"] == ["600"] _apply(config, attach) detach = manage.detach_microsoft_negative_keyword_list(config, list_id="900", campaign_ids=[CAMPAIGN]) _apply(config, detach) @@ -848,12 +896,12 @@ def test_callout_and_snippet_rules(self, api, config): assert "3–10 values" in _text(manage.draft_microsoft_structured_snippet(config, campaign_id=CAMPAIGN, header="Services", values=["a", "b"])) snippet = manage.draft_microsoft_structured_snippet(config, campaign_id=CAMPAIGN, header="Services", values=["Drain Cleaning", "Water Heaters", "Repiping"]) - assert snippet["changes"]["extensions"][0] == {"Type": "StructuredSnippetAdExtension", "Header": "Services", + assert _payload(snippet)["extensions"][0] == {"Type": "StructuredSnippetAdExtension", "Header": "Services", "Values": ["Drain Cleaning", "Water Heaters", "Repiping"]} def test_one_call_extension_per_campaign(self, api, config): preview = manage.draft_microsoft_call_extension(config, campaign_id=CAMPAIGN, phone_number="(217) 555-0100", country_code="us") - assert preview["changes"]["extensions"][0] == {"Type": "CallAdExtension", "PhoneNumber": "(217) 555-0100", + assert _payload(preview)["extensions"][0] == {"Type": "CallAdExtension", "PhoneNumber": "(217) 555-0100", "CountryCode": "US", "IsCallOnly": False} _apply(config, preview) again = manage.draft_microsoft_call_extension(config, campaign_id=CAMPAIGN, phone_number="(217) 555-0199", country_code="US") @@ -1038,24 +1086,23 @@ def test_broad_keyword_added_before_a_pending_manual_switch_refuses_it(self, api # -- finding 6: every bid and line of copy is on the approval surfaces def test_dialog_shows_keyword_bid_overrides(self, api, config): - from adloop.safety.approval import confirmation_message, display_fields + from adloop.safety.approval import confirmation_message preview = manage.draft_microsoft_ad_group(config, campaign_id=CAMPAIGN, name="Sewer", cpc_bid=5, keywords=[{"text": "sewer line", "match_type": "exact", "bid": 25}]) plan = preview_store.get_plan(preview["plan_id"]) - shown = _text(dict(display_fields(plan.changes))) - assert "sewer line [Exact] bid 25.0" in shown and "keyword_rows" not in shown + assert "sewer line [Exact] bid 25.0" in _text(plan.changes) and "keyword_rows" not in _text(plan.changes) assert "bid 25.0" in confirmation_message(plan) + assert plan.apply_only_payload["keyword_rows"][0]["Bid"] == {"Amount": 25.0} def test_dialog_shows_sitelink_descriptions(self, api, config): - from adloop.safety.approval import confirmation_message, display_fields + from adloop.safety.approval import confirmation_message preview = manage.draft_microsoft_sitelinks(config, campaign_id="600", sitelinks=[ {"link_text": "Water Heaters", "final_url": "https://example.com/water-heaters", "description1": "Same-day installs", "description2": "Tank and tankless"}]) plan = preview_store.get_plan(preview["plan_id"]) - shown = _text(dict(display_fields(plan.changes))) - assert "Same-day installs / Tank and tankless" in shown and '"extensions"' not in shown + assert "Same-day installs / Tank and tankless" in _text(plan.changes) and '"extensions"' not in _text(plan.changes) assert "Tank and tankless" in confirmation_message(plan) # -- finding 7: a partial create keeps its IDs and is never replayed @@ -1144,7 +1191,7 @@ def test_unchanged_windows_stay_and_disjoint_ones_go_in_first(self, api, config) {"day_of_week": "Monday", "start_hour": 9, "end_hour": 17}, # kept {"day_of_week": "Tuesday", "start_hour": 13, "end_hour": 17}, # no overlap: first ]) - ops = preview["changes"]["operations"] + ops = _payload(preview)["operations"] assert len(ops["schedule_add_first"]) == 1 and ops["schedule_delete"] == ["7002"] and ops["schedule_add_after"] == [] assert not any("serves at all hours" in w for w in preview["warnings"]) _apply(config, preview) @@ -1201,10 +1248,8 @@ class TestKeywordStatusOnCreate: """Finding 9: the approval surfaces say keywords are created Active.""" def test_keywords_in_a_live_ad_group_say_they_serve_immediately(self, api, config): - from adloop.safety.approval import display_fields - preview = manage.draft_microsoft_keywords(config, ad_group_id="11", keywords=["clogged drain"]) - shown = dict(display_fields(preview_store.get_plan(preview["plan_id"]).changes)) + shown = preview_store.get_plan(preview["plan_id"]).changes assert shown["status_on_create"] == "Active" assert shown["ad_group_status"] == "Active" and shown["campaign_status"] == "Active" assert any("can serve as soon as this is applied" in w for w in preview["warnings"]) @@ -1233,7 +1278,7 @@ def test_six_disjoint_windows_replaced_by_six_others_stay_within_seven_a_day(sel self._window(api, 7100 + i, "Monday", start, start + 1) new = [{"day_of_week": "Monday", "start_hour": h, "end_hour": h + 1} for h in range(12, 24, 2)] preview = manage.update_microsoft_campaign_targeting(config, campaign_id=CAMPAIGN, ad_schedule=new) - ops = preview["changes"]["operations"] + ops = _payload(preview)["operations"] assert len(ops["schedule_add_first"]) == 1 and len(ops["schedule_add_after"]) == 5 assert not any("serves at all hours" in w for w in preview["warnings"]) _apply(config, preview) @@ -1252,26 +1297,6 @@ def test_a_failure_names_the_windows_that_stay(self, api, config): assert "keeps Mon 09:00–17:00" in result["error"] and "serves at all hours" not in result["error"] assert self._schedule(api) == [("Monday", 9, 17)] - @pytest.mark.parametrize("with_locations", [False, True]) - def test_a_schedule_plan_from_before_the_fix_must_be_drafted_again(self, api, config, with_locations): - # Finding 2: the old plan shape put schedule windows in add/delete and - # carried no time zone mode; it is refused, never applied the old way. - self._window(api, 7001, "Monday", 9, 17) - preview = manage.update_microsoft_campaign_targeting( - config, campaign_id=CAMPAIGN, location_ids=["190", "200"] if with_locations else None, - ad_schedule=[{"day_of_week": "Monday", "start_hour": 10, "end_hour": 18}]) - plan = preview_store.get_plan(preview["plan_id"]) - ops = plan.changes["operations"] - ops["add"] += ops.pop("schedule_add_first") + ops.pop("schedule_add_after") - ops["delete"] += ops.pop("schedule_delete") - ops.pop("schedule_kept", None) - plan.changes["before"].pop("searcher_time_zone") - preview_store.store_plan(plan) - result = ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=False) - assert result.get("status") != "APPLIED" and "draft it again" in _text(result) - assert self._schedule(api) == [("Monday", 9, 17)] - assert not [c for c in api.calls if c["path"] == "CampaignCriterions" and c["method"] in ("POST", "DELETE")] - class TestGoalsWithoutInStorePilot: """The MaxConversions goal check must work for accounts outside Microsoft's in-store pilot.""" @@ -1282,14 +1307,18 @@ def test_counted_goals_are_counted(self, api, config): api.goals = [] assert manage._counted_goals(config, ACCOUNT, CUSTOMER) == 0 - def test_max_conversions_without_goals_still_warns(self, api, config): + def test_max_conversions_without_goals_warns_or_refuses(self, api, config): api.in_store_pilot = False api.goals = [] + # Already on MaxConversions: a target change only warns. update = manage.update_microsoft_campaign(config, campaign_id="600", target_cpa=25) assert any("nothing to optimize" in w for w in update["warnings"]) + # A switch to it, or a new campaign on it, is refused: Microsoft would refuse it. + switch = manage.update_microsoft_campaign(config, campaign_id=CAMPAIGN, bidding_strategy="MaxConversions") + assert "needs an active conversion goal" in _text(switch) and "plan_id" not in switch new = manage.draft_microsoft_campaign(config, name="New", daily_budget=10, languages=["English"], location_ids=["190"]) - assert any("nothing to optimize" in w for w in new["warnings"]) + assert "needs an active conversion goal" in _text(new) def test_an_unreadable_goal_list_is_unknown(self, api, config): api.fail[("POST", "ConversionGoals/QueryByIds")] = MicrosoftAdsApiError("Internal error", status=500) @@ -1397,7 +1426,9 @@ def test_preview_shows_images_target_and_alt_text(self, api, config, tmp_path, w assert preview["operation"] == "microsoft_add_image_extension" and preview["entity_type"] == "ad_group" changes = preview["changes"] assert changes["entity_name"] == "ad group 'Drains' in campaign 'Acme Plumbing - Search'" - assert changes["association_type"] == "AdGroup" and changes["entity_id"] == "11" + payload = _payload(preview) + assert payload["association_type"] == "AdGroup" and payload["entity_id"] == "11" + assert not {"association_type", "image_payloads", "ad_account_id", "customer_id"} & set(changes) assert changes["images"][0].endswith("PNG 1200x628 (1.91:1), 0.1 KB") assert changes["images"][1] == "https://cdn.example.com/team.jpg: JPEG 1406x736 (1.91:1), 0.0 KB" assert changes["alt_text"] == "Plumber clearing a drain" and changes["display_text"] == "Same-day drain service" @@ -1408,6 +1439,7 @@ def test_preview_shows_images_target_and_alt_text(self, api, config, tmp_path, w # The approval dialog shows the images, never the pinned payloads. message = confirmation_message(get_plan(preview["plan_id"])) assert "1200x628" in message and "image payloads" not in message and "sha256" not in message + assert "sha256" not in _approval_surfaces(config, preview) plain = manage.draft_microsoft_image_extension(config, campaign_id=CAMPAIGN, alt_text="Van", image_paths=[_file(tmp_path, "van2.png", _png(1910, 1000))]) assert plain["changes"]["layouts"] == ["SearchSingle"] and "display_text" not in plain["changes"] @@ -1423,6 +1455,7 @@ def test_apply_uploads_media_then_creates_then_links(self, api, config, tmp_path config, ad_group_id="11", image_paths=[_file(tmp_path, "van.png", png)], image_urls=["https://cdn.example.com/team.jpg"], alt_text="Plumber clearing a drain", display_text="Same-day drain service", final_url="https://example.com/drain") + payload = _payload(preview) result = _apply(config, preview) writes = [c["path"] for c in api.writes()] assert writes == ["Media", "AdExtensions", "AdExtensionsAssociations/Set"] @@ -1435,7 +1468,7 @@ def test_apply_uploads_media_then_creates_then_links(self, api, config, tmp_path first_media = int(result["media_ids"][0]) assert created[0] == { "Type": "ImageAdExtension", "AlternativeText": "Plumber clearing a drain", - "Description": preview["changes"]["image_payloads"][0]["name"][:100], + "Description": payload["image_payloads"][0]["name"][:100], "ImageMediaIds": [first_media], "Images": [{"Asset": {"Type": "ImageAsset", "Id": first_media, "SubType": "LandscapeImageMedia"}}], "Layouts": ["SearchSingle", "SearchMultiple"], "DisplayText": "Same-day drain service", @@ -1630,3 +1663,178 @@ def test_uploaded_images_are_used_by_id(self, api, config, tmp_path): assert "Upload 1: upload up_missing0000 was not found" in _text(missing) and "plan_id" not in missing finally: uploads.set_upload_store(None) + + +# --------------------------------------------------------------------------- +# Upstream review (#130) +# --------------------------------------------------------------------------- + + +class TestReviewBroadMatch: + """Broad match only with conversion-based bidding; Maximize Clicks does not count.""" + + def test_broad_keywords_are_refused_on_maximize_clicks(self, api, config): + api.campaigns["600"]["BiddingScheme"] = {"Type": "MaxClicks"} + refused = manage.draft_microsoft_keywords(config, ad_group_id="21", + keywords=[{"text": "acme", "match_type": "broad"}]) + assert "Broad match needs conversion-based bidding" in _text(refused) and "plan_id" not in refused + + @pytest.mark.parametrize("scheme", ["MaxConversions", "MaxConversionValue", "TargetCpa", "TargetRoas", + "MaxConversionValueBiddingScheme"]) + def test_broad_keywords_are_allowed_on_conversion_bidding(self, api, config, scheme): + api.campaigns["600"]["BiddingScheme"] = {"Type": scheme} + preview = manage.draft_microsoft_keywords(config, ad_group_id="21", + keywords=[{"text": "acme", "match_type": "broad"}]) + assert "plan_id" in preview, preview + + def test_moving_to_maximize_clicks_with_broad_keywords_is_refused(self, api, config): + # CAMPAIGN has the active broad keyword 'plumber'. + result = manage.update_microsoft_campaign(config, campaign_id=CAMPAIGN, bidding_strategy="MaxClicks") + assert "broad match needs conversion-based bidding" in _text(result) and "plan_id" not in result + + def test_a_broad_keyword_added_after_a_maximize_clicks_draft_fails_the_apply(self, api, config): + preview = manage.update_microsoft_campaign(config, campaign_id="600", bidding_strategy="MaxClicks") + api.keywords["299"] = {"Id": 299, "Text": "acme", "MatchType": "Broad", "Bid": {"Amount": None}, + "Status": "Active", "_group": "21"} + result = ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=False) + assert result.get("status") != "APPLIED" and "now has 1 active broad-match" in _text(result) + + def test_the_keyword_read_flags_broad_on_maximize_clicks(self, api, config): + api.campaigns["600"]["BiddingScheme"] = {"Type": "MaxClicks"} + api.keywords["299"] = {"Id": 299, "Text": "acme", "MatchType": "Broad", "Bid": {"Amount": None}, + "Status": "Active", "_group": "21"} + insights = " ".join(read.get_microsoft_keywords(config, campaign_id="600")["insights"]) + assert "without conversion-based bidding" in insights and "Maximize Clicks" in insights + + +class TestReviewCriterionRemoval: + def test_the_draft_names_the_criterion(self, api, config): + preview = manage.remove_microsoft_entity(config, entity_type="campaign_criterion", entity_id=f"{CAMPAIGN}~1002") + changes = preview["changes"] + assert changes["entity_name"] == "location Los Angeles, California (excluded)" + assert changes["campaign_name"] == "Acme Plumbing - Search" and changes["criterion_type"] == "Location" + assert "request" not in changes + + def test_the_last_targeted_location_cannot_be_removed(self, api, config): + result = manage.remove_microsoft_entity(config, entity_type="campaign_criterion", entity_id=f"{CAMPAIGN}~1001") + assert "last targeted location" in _text(result) and "update_microsoft_campaign_targeting" in _text(result) + assert "plan_id" not in result + + def test_a_location_with_others_left_can_go_but_not_once_it_is_the_last(self, api, config): + api.criteria[CAMPAIGN].append({"Id": 1004, "Type": "BiddableCampaignCriterion", "CampaignId": int(CAMPAIGN), + "Criterion": {"Type": "Radius", "Name": "Downtown", "Radius": 10, + "RadiusUnit": "Miles"}}) + preview = manage.remove_microsoft_entity(config, entity_type="campaign_criterion", entity_id=f"{CAMPAIGN}~1001") + assert preview["changes"]["entity_name"] == "location Springfield, Illinois (targeted)" + api.criteria[CAMPAIGN] = [c for c in api.criteria[CAMPAIGN] if c["Id"] != 1004] + result = ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=True) + assert result["status"] == "DRY_RUN_FAILED" and "last targeted location" in result["error"] + + def test_an_unknown_criterion_is_reported(self, api, config): + assert "has no target criterion 4242" in _text(manage.remove_microsoft_entity( + config, entity_type="campaign_criterion", entity_id=f"{CAMPAIGN}~4242")) + + +class TestReviewPayloads: + """Request bodies, snapshots and ids live in apply_only_payload, never on an approval surface.""" + + @pytest.mark.parametrize("draft", [ + lambda c: manage.update_microsoft_campaign(c, campaign_id="600", target_cpa=40), + lambda c: manage.update_microsoft_campaign_targeting(c, campaign_id=CAMPAIGN, location_ids=["190", "200"]), + lambda c: manage.draft_microsoft_campaign(c, name="New", daily_budget=10, languages=["English"], + location_ids=["190"]), + lambda c: manage.draft_microsoft_ad_group(c, campaign_id=CAMPAIGN, name="Sewer", cpc_bid=5, keywords=["sewer"]), + lambda c: manage.update_microsoft_ad_group(c, ad_group_id="11", cpc_bid=9), + lambda c: manage.draft_microsoft_keywords(c, ad_group_id="11", keywords=["clogged drain"]), + lambda c: manage.update_microsoft_keyword_bids(c, ad_group_id="11", bids=[{"keyword_id": "102", "bid": 10}]), + lambda c: manage.add_microsoft_negative_keywords(c, campaign_id=CAMPAIGN, keywords=["cheap"]), + lambda c: manage.propose_microsoft_negative_keyword_list(c, list_name="New list", keywords=["cheap"], + campaign_ids=["600"]), + lambda c: manage.update_microsoft_responsive_search_ad(c, ad_id="301", path2="fast"), + lambda c: manage.draft_microsoft_callouts(c, campaign_id="600", callouts=["Licensed", "Insured"]), + lambda c: manage.remove_microsoft_entity(c, entity_type="keyword", entity_id="102"), + ]) + def test_payloads_stay_off_every_approval_surface(self, api, config, draft): + preview = draft(config) + assert "plan_id" in preview, preview + ads_write.confirm_and_apply(config, plan_id=preview["plan_id"], dry_run=True) + plan = preview_store.get_plan(preview["plan_id"]) + hidden = {"update", "before", "operations", "campaign", "criteria", "ad_group", "keyword_rows", + "negative_rows", "request", "image_payloads", "extensions", "entity_kind", "ad", + "update_audience_adjustment", "ad_account_id", "customer_id", "campaign_ids"} + assert not hidden & set(plan.changes), sorted(hidden & set(plan.changes)) + assert {"ad_account_id", "customer_id"} <= set(plan.apply_only_payload) + surfaces = _approval_surfaces(config, preview) + for marker in ('"Type": "BiddableCampaignCriterion"', '"MatchType":', '"Asset":', "customer id", "ad account id"): + assert marker not in surfaces, marker + + +class TestReviewAccountScans: + def _reads(self, api, path): + return sum(1 for c in api.calls if c["path"] == path) + + def test_an_rsa_update_reads_only_its_own_ad_group_after_the_draft(self, api, config): + api.ad_groups["13"] = {"Id": 13, "Name": "Sewers", "Status": "Active", "_campaign": CAMPAIGN} + api.ad_groups["22"] = {"Id": 22, "Name": "Brand two", "Status": "Active", "_campaign": "600"} + preview = manage.update_microsoft_responsive_search_ad(config, ad_id="301", path2="fast") + api.calls.clear() + _apply(config, preview) + # Dry run and apply: one ad group list of the ad's campaign and one ad list of its group each. + assert self._reads(api, "AdGroups/QueryByCampaignId") == 2 + assert self._reads(api, "Ads/QueryByAdGroupId") == 2 + + def test_a_keyword_removal_reads_only_its_own_ad_group_after_the_draft(self, api, config): + preview = manage.remove_microsoft_entity(config, entity_type="keyword", entity_id="103") + api.calls.clear() + _apply(config, preview) + assert self._reads(api, "AdGroups/QueryByCampaignId") == 2 + assert {c["body"]["AdGroupId"] for c in api.calls if c["path"] == "Keywords/QueryByAdGroupId"} == {"12"} + + def test_campaign_reads_ask_once_per_campaign_for_its_targeting(self, api, config): + read.get_microsoft_campaigns(config) + queries = [c["body"] for c in api.calls if c["path"] == "CampaignCriterions/QueryByIds"] + assert [q["CriterionType"] for q in queries] == ["Targets"] * len(api.campaigns) + + def test_a_refused_targets_query_falls_back_to_one_per_type(self, api, config): + api.refuse_targets_query = True + rows = {r["campaign_id"]: r for r in read.get_microsoft_campaigns(config)["campaigns"]} + assert rows[CAMPAIGN]["locations"]["included"] == ["Springfield, Illinois"] + kinds = [c["body"]["CriterionType"] for c in api.calls if c["path"] == "CampaignCriterions/QueryByIds"] + assert kinds.count("Targets") == 1 and kinds.count("Location") == len(api.campaigns) + + +class TestReviewReads: + def test_radius_targets_are_named(self, api, config): + api.criteria[CAMPAIGN].append({"Id": 1004, "Type": "BiddableCampaignCriterion", "CampaignId": int(CAMPAIGN), + "Criterion": {"Type": "Radius", "Name": "Downtown", "Radius": 10, + "RadiusUnit": "Miles"}}) + rows = {r["campaign_id"]: r for r in read.get_microsoft_campaigns(config)["campaigns"]} + assert "Downtown (10 Miles)" in rows[CAMPAIGN]["locations"]["included"] + + def test_an_ad_group_without_its_own_audience_setting_inherits_the_campaign(self, api, config): + api.campaigns[CAMPAIGN]["AudienceAdsBidAdjustment"] = -100 + api.ad_groups["11"]["AudienceAdsBidAdjustment"] = None + rows = {r["ad_group_id"]: r for r in read.get_microsoft_ad_groups(config)["ad_groups"]} + assert rows["11"]["audience_network"] == {"on": False, "bid_adjustment": -100, "set_on": "campaign"} + api.campaigns[CAMPAIGN]["AudienceAdsBidAdjustment"] = None + rows = {r["ad_group_id"]: r for r in read.get_microsoft_ad_groups(config)["ad_groups"]} + assert rows["11"]["audience_network"]["on"] and rows["11"]["audience_network"]["set_on"] == "Microsoft default" + insights = " ".join(read.get_microsoft_ad_groups(config)["insights"]) + assert "Audience Network" in insights + + +class TestReviewValidation: + def test_target_cpa_and_max_cpc_on_a_manual_campaign_are_refused(self, api, config): + # CAMPAIGN is EnhancedCpc: neither value would reach Microsoft. + assert "target_cpa goes with MaxConversions" in _text( + manage.update_microsoft_campaign(config, campaign_id=CAMPAIGN, target_cpa=30)) + assert "max_cpc caps" in _text(manage.update_microsoft_campaign(config, campaign_id=CAMPAIGN, max_cpc=5)) + assert "max_cpc caps" in _text(manage.update_microsoft_campaign( + config, campaign_id=CAMPAIGN, bidding_strategy="ManualCpc", max_cpc=5)) + + def test_seven_schedule_windows_a_day_are_allowed(self, api, config): + seven = [{"day_of_week": "Monday", "start_hour": h, "end_hour": h + 1} for h in range(8, 15)] + assert "plan_id" in manage.update_microsoft_campaign_targeting(config, campaign_id=CAMPAIGN, ad_schedule=seven) + eight = seven + [{"day_of_week": "Monday", "start_hour": 20, "end_hour": 21}] + assert "At most 7 ad_schedule windows on Monday" in _text( + manage.update_microsoft_campaign_targeting(config, campaign_id=CAMPAIGN, ad_schedule=eight)) diff --git a/tests/test_oauth_redirect.py b/tests/test_oauth_redirect.py index 6043e8b8..89ad839b 100644 --- a/tests/test_oauth_redirect.py +++ b/tests/test_oauth_redirect.py @@ -92,3 +92,33 @@ def real(): stop.set() assert result == {"code": "c1", "state": "s1"} assert elapsed < 2.0 + + +def _get(port: int, query: str) -> bytes: + sock = _connect(port) + sock.sendall(f"GET /callback?{query} HTTP/1.1\r\nHost: localhost\r\n\r\n".encode()) + data = sock.recv(4096) + sock.close() + return data + + +def test_a_request_with_another_state_is_answered_and_ignored(): + port = _free_port() + + def browser(): + time.sleep(0.1) + stray = _get(port, "code=forged&state=other") + assert stray.startswith((b"HTTP/1.0 400", b"HTTP/1.1 400")) + _get(port, "code=good&state=mine") + + threading.Thread(target=browser, daemon=True).start() + started = time.monotonic() + result = listen_once(f"http://127.0.0.1:{port}/callback", 5.0, provider="Test", state="mine") + assert result == {"code": "good", "state": "mine"} + assert time.monotonic() - started < 3.0 + + +def test_the_listener_picks_a_free_port_and_names_it(): + with oauth_redirect.RedirectListener(host="127.0.0.1", path="/callback") as listener: + assert listener.port > 0 + assert listener.redirect_uri == f"http://127.0.0.1:{listener.port}/callback" From f2a4ca40d7f2a9ebc1e94020abf291170f40e8da Mon Sep 17 00:00:00 2001 From: Illia Sapryga Date: Sun, 8 Nov 2026 16:38:25 -0600 Subject: [PATCH 5/6] Microsoft Advertising: split manage.py into per-area handlers manage.py (2.4k lines, two parallel ~20-branch dispatchers) becomes the package microsoft_ads/manage: _common (constants, request and plan helpers, bidding, Step and Handler), campaigns, targeting, ad_groups, negatives, ads, extensions and removal. Each area drafts its plans and registers its operations in HANDLERS (operation -> dry-run check, apply); the package merges them into one table that preflight and apply_plan look up. The code of every check and apply moved unchanged; imports from adloop.microsoft_ads.manage keep working. --- README.md | 3 +- src/adloop/microsoft_ads/manage.py | 2599 ----------------- src/adloop/microsoft_ads/manage/__init__.py | 178 ++ src/adloop/microsoft_ads/manage/_common.py | 310 ++ src/adloop/microsoft_ads/manage/ad_groups.py | 400 +++ src/adloop/microsoft_ads/manage/ads.py | 209 ++ src/adloop/microsoft_ads/manage/campaigns.py | 334 +++ src/adloop/microsoft_ads/manage/extensions.py | 698 +++++ src/adloop/microsoft_ads/manage/negatives.py | 390 +++ src/adloop/microsoft_ads/manage/removal.py | 196 ++ src/adloop/microsoft_ads/manage/targeting.py | 332 +++ tests/test_microsoft_ads_manage.py | 16 + 12 files changed, 3065 insertions(+), 2600 deletions(-) delete mode 100644 src/adloop/microsoft_ads/manage.py create mode 100644 src/adloop/microsoft_ads/manage/__init__.py create mode 100644 src/adloop/microsoft_ads/manage/_common.py create mode 100644 src/adloop/microsoft_ads/manage/ad_groups.py create mode 100644 src/adloop/microsoft_ads/manage/ads.py create mode 100644 src/adloop/microsoft_ads/manage/campaigns.py create mode 100644 src/adloop/microsoft_ads/manage/extensions.py create mode 100644 src/adloop/microsoft_ads/manage/negatives.py create mode 100644 src/adloop/microsoft_ads/manage/removal.py create mode 100644 src/adloop/microsoft_ads/manage/targeting.py diff --git a/README.md b/README.md index 4b762a3c..04a6c6e0 100644 --- a/README.md +++ b/README.md @@ -646,7 +646,8 @@ src/adloop/ │ ├── auth.py # Entra sign-in (browser auth code + PKCE, device-code fallback), refresh tokens │ ├── client.py # REST v13 client — Campaign Management, Customer Management, Reporting services │ ├── read.py # Accounts, campaigns, ad groups, keywords, ads, reports, search terms, conversion audit -│ ├── manage.py # Drafts, preflight and apply for campaigns, targeting, keywords, negatives, ads, extensions +│ ├── manage/ # Drafts, dry-run checks and applies per area (campaigns, targeting, ad groups, negatives, +│ │ # ads, extensions, removal), one operation → handler table │ └── write.py # Budget and status drafts; routes every microsoft_ plan to its preflight and apply ├── oauth_redirect.py # Localhost listener for sign-in redirects (free port, waits for its state) └── safety/ diff --git a/src/adloop/microsoft_ads/manage.py b/src/adloop/microsoft_ads/manage.py deleted file mode 100644 index 4c63660a..00000000 --- a/src/adloop/microsoft_ads/manage.py +++ /dev/null @@ -1,2599 +0,0 @@ -"""Microsoft Advertising management: campaigns, targeting, ad groups, keywords, -negatives, responsive search ads, ad extensions (image extensions included) -and removals. - -Every function here drafts a :class:`ChangePlan` (platform ``microsoft``, -operation ``microsoft_*``) and returns its preview; nothing changes until -``confirm_and_apply``. :mod:`adloop.microsoft_ads.write` routes these -operations to :func:`preflight` and :func:`apply_plan` below. - -Microsoft's Campaign Management API has no validate-only mode, so: - -- **Updates** store a snapshot of every field they change; the dry run and - the apply re-read the entity and refuse when one of those fields was - edited in Microsoft Advertising since the preview. -- **Creates** re-check their parents, the safety caps and (for named - objects) that the name is still free, so a retried apply after a partial - failure refuses instead of creating a second copy. -- **Multi-step applies** (a campaign and then its targeting, a list and then - its attachments) report exactly what was created when a later step fails. - -A plan's ``changes`` hold what the person approves (names, before → after); -request bodies, snapshots and ids live in ``ChangePlan.apply_only_payload``, -which no preview, dialog, card or audit entry shows. The dry run and the -apply read both through ``plan.apply_payload()``. - -REST conventions (learn.microsoft.com/advertising/campaign-management-service): -add is POST, update PUT, delete DELETE on the collection path; polymorphic -objects carry a ``Type`` discriminator; on update an omitted field stays as -it is and a list that is sent replaces the old one. -""" - -from __future__ import annotations - -import base64 -import copy -import hashlib -import json -from typing import TYPE_CHECKING, Any - -from adloop.microsoft_ads.auth import MicrosoftAdsApiError -from adloop.microsoft_ads.client import campaign_request, fault_details -from adloop.microsoft_ads.read import ( - CONVERSION_BASED_STRATEGIES, - _ad_groups, - _ads, - _bidding, - _campaigns, - _conversion_goals, - _customer, - _keywords, - _money, - account_meta, - is_negative, - target_criterions, -) -from adloop.microsoft_ads.write import _blocked as _guard -from adloop.microsoft_ads.write import ( - _validation_error, - find_entity, - store_plan_preview, -) - -if TYPE_CHECKING: - from adloop.config import AdLoopConfig - from adloop.safety.preview import ChangePlan - -# The strategies a draft can set. -STRATEGIES = ("ManualCpc", "EnhancedCpc", "MaxClicks", "MaxConversions") -# Broad match needs one of these (read.CONVERSION_BASED_STRATEGIES); Maximize -# Clicks is automated but not conversion-based, so it does not count. -_CONVERSION_BASED = CONVERSION_BASED_STRATEGIES -_MANUAL = {"ManualCpc", "EnhancedCpc"} -# Strategies that take a maximum CPC cap. -_CAPPED = {"MaxClicks", "MaxConversions"} -_ALTERNATIVES = "MaxClicks, EnhancedCpc or ManualCpc" -MATCH_TYPES = ("Exact", "Phrase", "Broad") -NEGATIVE_MATCH_TYPES = ("Exact", "Phrase") -NETWORKS = ("OwnedAndOperatedOnly", "OwnedAndOperatedAndSyndicatedSearch") -INTENTS = ("PeopleIn", "PeopleInOrSearchingForOrViewingPages") -DAYS = ("Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday") -_MINUTES = {0: "Zero", 15: "Fifteen", 30: "Thirty", 45: "FortyFive"} -_PINS = { - "headline_1": "Headline1", "headline_2": "Headline2", "headline_3": "Headline3", - "headline1": "Headline1", "headline2": "Headline2", "headline3": "Headline3", - "description_1": "Description1", "description_2": "Description2", - "description1": "Description1", "description2": "Description2", -} -_EXTENSION_TYPES = ("SitelinkAdExtension, CalloutAdExtension, StructuredSnippetAdExtension, CallAdExtension, " - "ImageAdExtension") -_LIST_TYPE = "NegativeKeywordList" -_MAX_LISTS_PER_CAMPAIGN = 20 -_CHUNK = 100 - - -# --------------------------------------------------------------------------- -# Shared helpers -# --------------------------------------------------------------------------- - - -def _ctx(config: AdLoopConfig, ad_account_id: str) -> tuple[dict, str, str]: - meta = account_meta(config, ad_account_id) - return meta, meta["ad_account_id"], _customer(config, meta) - - -def _clean(values: Any) -> list[str]: - if values is None: - return [] - if isinstance(values, (str, int)): - values = [values] - return [str(v).strip() for v in values if str(v).strip()] - - -def _same(a: Any, b: Any) -> bool: - return json.dumps(a, sort_keys=True, default=str) == json.dumps(b, sort_keys=True, default=str) - - -def _check_url(url: str, errors: list[str], warnings: list[str], field: str = "final_url") -> None: - if not url.startswith(("http://", "https://")): - errors.append(f"{field} must start with http:// or https://") - return - from adloop.ads.write import _validate_urls - - bad, inconclusive = _validate_urls([url]) - if bad.get(url): - errors.append(f"{field} '{url}' is not reachable: {bad[url]}") - warnings.extend(inconclusive.values()) - - -_ID_FIELDS = ("CampaignIds", "AdGroupIds", "KeywordIds", "AdIds", "CampaignCriterionIds", "ListItemIds", "MediaIds") - - -def _created_ids(payload: dict) -> list[str]: - """IDs a create reported as done (failed items come back as null).""" - ids: list[str] = [] - for field in _ID_FIELDS: - ids += [str(i) for i in payload.get(field) or [] if i is not None] - ids += [str((i or {}).get("Id")) for i in payload.get("AdExtensionIdentities") or [] if i and i.get("Id")] - if payload.get("SharedEntityId"): - ids.append(str(payload["SharedEntityId"])) - for group in payload.get("NegativeKeywordIds") or []: - ids += [str(i) for i in (group or {}).get("Ids") or [] if i is not None] - return ids - - -def _partial_errors(payload: dict) -> list[dict]: - entries = [e for e in payload.get("PartialErrors") or [] if e] - for nested in payload.get("NestedPartialErrors") or []: - if not isinstance(nested, dict): - continue - entries.extend(e for e in nested.get("BatchErrors") or [] if e) - if nested.get("ErrorCode") or nested.get("Message"): - entries.append(nested) - return entries - - -def _raise_partial(payload: dict, what: str) -> None: - entries = _partial_errors(payload) - if not entries: - return - _codes, message, _tracking = fault_details({"PartialErrors": entries}) - created = _created_ids(payload) - if created: - # Some items were created and some refused: replaying the plan would - # create the successful ones again. - from adloop.safety.outcomes import PartialApplyError - - raise PartialApplyError( - f"Microsoft created part of the {what} (ids {created}) and refused the rest: {message or entries}", - created={what: created}, - ) - raise MicrosoftAdsApiError(f"Microsoft refused the {what}: {message or entries}") - - -def _call(config: AdLoopConfig, changes: dict, method: str, path: str, body: dict, what: str) -> dict: - try: - payload = campaign_request( - config, path, body, account_id=changes["ad_account_id"], customer_id=changes.get("customer_id", ""), - method=method, mutation=True, - ) - except MicrosoftAdsApiError as exc: - if method == "POST" and (exc.status == 0 or exc.status >= 500): - # The request may have reached Microsoft and created something: - # these creates have no idempotency, so replaying the plan could - # create it twice. Retire the plan and say so. - from adloop.safety.outcomes import PartialApplyError - - raise PartialApplyError( - f"Microsoft did not confirm the {what} ({exc}); it may or may not have been created. " - "Check the account before drafting it again.", - unknown=True, - ) from None - raise - _raise_partial(payload, what) - return payload - - -class _Progress: - """What a multi-step apply already changed, for an honest error. - - Once one step has changed the account, a failure in a later step retires - the plan (PartialApplyError) instead of leaving it to be replayed. - """ - - def __init__(self) -> None: - self.done: list[str] = [] - # IDs of what the earlier steps created, by kind, for the error. - self.created: dict[str, list[str]] = {} - - def step(self, what: str, fn): - from adloop.safety.outcomes import PartialApplyError - - try: - return fn() - except PartialApplyError as exc: - if self.done: - raise PartialApplyError( - f"{exc} (after: {'; '.join(self.done)})", - created={**self.created, **exc.created, "done": list(self.done)}, unknown=exc.unknown, - ) from None - raise - except Exception as exc: - if self.done: - raise PartialApplyError( - f"{what} failed after these steps succeeded: {'; '.join(self.done)}. " - f"Microsoft said: {exc}. Check the account before drafting again.", - created={**self.created, "done": list(self.done)}, - ) from None - raise - - -def _plan(operation: str, entity_type: str, entity_id: str, account: str, customer: str, changes: dict, - payload: dict | None = None, *, warnings: list[str] | None = None, double: bool = False) -> dict: - """Store a plan: ``changes`` for the person approving, ``payload`` for the dry run and the apply.""" - return store_plan_preview( - operation, entity_type, entity_id, account, changes, - {"ad_account_id": account, "customer_id": customer, **(payload or {})}, - warnings=warnings, double=double, - ) - - -def _chunks(items: list, size: int = _CHUNK) -> list[list]: - return [items[i : i + size] for i in range(0, len(items), size)] - - -# --------------------------------------------------------------------------- -# Bidding -# --------------------------------------------------------------------------- - - -def bidding_scheme(strategy: str, *, target_cpa: float | None, max_cpc: float | None) -> dict: - scheme: dict[str, Any] = {"Type": strategy} - if strategy == "MaxConversions" and target_cpa is not None: - scheme["TargetCpa"] = round(float(target_cpa), 2) - if strategy in _CAPPED and max_cpc is not None: - scheme["MaxCpc"] = {"Amount": round(float(max_cpc), 2)} - return scheme - - -def _strategy_name(scheme: dict | None) -> str: - return str((scheme or {}).get("Type") or "").replace("BiddingScheme", "") - - -def _counted_goals(config: AdLoopConfig, account: str, customer: str) -> int: - try: - goals = _conversion_goals(config, account, customer) - except MicrosoftAdsApiError: - return -1 - return sum(1 for g in goals if g.get("Status") == "Active" and not g.get("ExcludeFromBidding")) - - -def _no_goal_refusal(strategy: str) -> str: - return ( - f"{strategy} needs an active conversion goal that counts toward Conversions, and this account has " - "none: Microsoft refuses the campaign (ConversionGoalCriteriaNotMetForBiddingScheme). Set up a " - "conversion goal first (get_microsoft_conversion_setup shows what exists), or use " - f"{_ALTERNATIVES} for now." - ) - - -def _goals_unknown_warning(strategy: str) -> str: - return (f"The conversion goals could not be read; Microsoft refuses {strategy} without an active " - "conversion goal that counts toward Conversions.") - - -def _broad_refusal(count: int, strategy: str) -> str: - return ( - f"The campaign has {count} active broad-match keyword(s), and broad match needs conversion-based " - f"bidding (MaxConversions, MaxConversionValue or a target CPA/ROAS); {strategy} would buy whatever " - "a loose match brings. Change them to phrase or exact first." - ) - - -# --------------------------------------------------------------------------- -# Campaign settings -# --------------------------------------------------------------------------- - - -def update_microsoft_campaign( - config: AdLoopConfig, - *, - ad_account_id: str = "", - campaign_id: str = "", - name: str = "", - bidding_strategy: str = "", - target_cpa: float | None = None, - max_cpc: float | None = None, - tracking_url_template: str | None = None, - final_url_suffix: str | None = None, -) -> dict: - """Draft campaign setting changes: name, bid strategy, tracking template, final URL suffix.""" - operation = "microsoft_update_campaign" - blocked = _guard(operation, config) - if blocked: - return blocked - errors: list[str] = [] - campaign_id = str(campaign_id or "").strip() - if not campaign_id: - errors.append("campaign_id is required") - if name and len(name.strip()) > 128: - errors.append("name is at most 128 characters.") - strategy = (bidding_strategy or "").strip() - if strategy == "TargetCpa": - strategy = "MaxConversions" - if strategy and strategy not in STRATEGIES: - errors.append(f"bidding_strategy must be one of {list(STRATEGIES)}.") - if target_cpa is not None and (strategy or "") not in ("", "MaxConversions"): - errors.append("target_cpa goes with MaxConversions.") - if max_cpc is not None and strategy and strategy not in _CAPPED: - errors.append(f"max_cpc caps {' or '.join(sorted(_CAPPED))} bids; a {strategy} campaign's bids are set " - "on its ad groups and keywords.") - template = None if tracking_url_template is None else tracking_url_template.strip() - if template and not template.startswith(("http://", "https://", "{lpurl}", "{unescapedlpurl}")): - errors.append("tracking_url_template must start with {lpurl}, {unescapedlpurl}, http:// or https://.") - if errors: - return _validation_error(errors) - meta, account, customer = _ctx(config, ad_account_id) - found = find_entity(config, account, customer, "campaign", campaign_id) - if not found: - return {"error": f"Microsoft campaign '{campaign_id}' was not found in account {account}."} - campaign = found["entity"] - update: dict[str, Any] = {"Id": campaign_id} - shown: dict[str, Any] = {} - warnings: list[str] = [] - touched: list[str] = [] - if name and name.strip() != campaign.get("Name"): - others = {str(c.get("Name")).lower() for c in _campaigns(config, account, customer) if str(c.get("Id")) != campaign_id} - if name.strip().lower() in others: - return _validation_error([f"Another campaign is already named '{name.strip()}'."]) - update["Name"] = name.strip() - shown["name"] = {"from": campaign.get("Name"), "to": name.strip()} - touched.append("Name") - current_scheme = campaign.get("BiddingScheme") or {} - if strategy or target_cpa is not None or max_cpc is not None: - chosen = strategy or _strategy_name(current_scheme) - if chosen not in STRATEGIES: - return _validation_error([f"The campaign uses {chosen or 'an unknown strategy'}; pass bidding_strategy explicitly."]) - if target_cpa is not None and chosen != "MaxConversions": - return _validation_error([f"target_cpa goes with MaxConversions; this campaign uses {chosen}. Pass " - "bidding_strategy='MaxConversions' to switch."]) - if max_cpc is not None and chosen not in _CAPPED: - return _validation_error([f"max_cpc caps {' or '.join(sorted(_CAPPED))} bids; this campaign uses " - f"{chosen}, whose bids are set on its ad groups and keywords."]) - has_cap = (current_scheme.get("MaxCpc") or {}).get("Amount") is not None - if max_cpc is not None and not has_cap and chosen in _CAPPED: - return _validation_error([ - "Microsoft no longer lets a campaign add a maximum CPC to automated bidding; it can " - "only change or remove an existing one." - ]) - keep_cap = (current_scheme.get("MaxCpc") or {}).get("Amount") if chosen == _strategy_name(current_scheme) else None - scheme = bidding_scheme( - chosen, - target_cpa=target_cpa if target_cpa is not None else (current_scheme.get("TargetCpa") if chosen == "MaxConversions" and _strategy_name(current_scheme) == "MaxConversions" else None), - max_cpc=max_cpc if max_cpc is not None else keep_cap, - ) - update["BiddingScheme"] = scheme - touched.append("BiddingScheme") - shown["bidding"] = {"from": _bidding(current_scheme), "to": _bidding(scheme), "currency": meta["currency"]} - switching = chosen != _strategy_name(current_scheme) - if switching: - warnings.append("Changing the bid strategy restarts Microsoft's learning period; expect a week or two of unsettled results.") - if chosen in _CONVERSION_BASED: - goals = _counted_goals(config, account, customer) - if goals == 0 and switching: - return _validation_error([_no_goal_refusal(chosen)]) - if goals == 0: - warnings.append(f"No active conversion goal counts toward Conversions: {chosen} has nothing to optimize for.") - elif goals < 0: - warnings.append(_goals_unknown_warning(chosen)) - old_cap = (current_scheme.get("MaxCpc") or {}).get("Amount") - new_cap = (scheme.get("MaxCpc") or {}).get("Amount") - try: - _check_bid(old_cap, new_cap, config) - except Exception as e: # SafetyViolation - return {"error": f"Maximum CPC: {e}"} - if chosen not in _CONVERSION_BASED: - broad = _active_broad_keywords(config, account, customer, campaign_id) - if broad: - return _validation_error([_broad_refusal(len(broad), chosen)]) - for field, value, api_name in (("tracking_url_template", template, "TrackingUrlTemplate"), - ("final_url_suffix", None if final_url_suffix is None else final_url_suffix.strip(), "FinalUrlSuffix")): - if value is None or value == (campaign.get(api_name) or ""): - continue - update[api_name] = value - touched.append(api_name) - shown[field] = {"from": campaign.get(api_name) or None, "to": value or None} - if value == "": - warnings.append(f"{field} is removed.") - if len(update) == 1: - return {"error": "Nothing to change: pass at least one setting that differs from the campaign."} - return _plan( - operation, "campaign", campaign_id, account, customer, - {"entity_name": campaign.get("Name"), "campaign_status": campaign.get("Status"), "changes": shown}, - {"update": update, "before": {k: copy.deepcopy(campaign.get(k)) for k in sorted(set(touched))}}, - warnings=warnings, - ) - - -# --------------------------------------------------------------------------- -# Targeting: locations, location intent, ad schedule -# --------------------------------------------------------------------------- - - -def _current_targeting(config: AdLoopConfig, account: str, customer: str, campaign_id: str) -> dict: - found = target_criterions(config, account, customer, campaign_id, ("Location", "LocationIntent", "DayTime")) - included = {} - excluded = {} - for c in found["Location"]: - crit = c.get("Criterion") or {} - entry = {"criterion_id": str(c.get("Id")), "name": crit.get("DisplayName") or str(crit.get("LocationId"))} - target = excluded if is_negative(c) else included - target[str(crit.get("LocationId"))] = entry - intent = found["LocationIntent"] - schedule = found["DayTime"] - return { - "included": included, - "excluded": excluded, - "intent": {"criterion_id": str(intent[0].get("Id")), - "option": (intent[0].get("Criterion") or {}).get("IntentOption")} if intent else None, - "schedule": [ - {"criterion_id": str(c.get("Id")), **{k: (c.get("Criterion") or {}).get(k) - for k in ("Day", "FromHour", "FromMinute", "ToHour", "ToMinute")}} - for c in schedule - ], - } - - -def _schedule_blocks(schedule: list, errors: list[str]) -> list[dict]: - blocks = [] - for i, raw in enumerate(schedule or []): - if not isinstance(raw, dict): - errors.append(f"ad_schedule[{i}] must be an object with day_of_week, start_hour, end_hour.") - continue - day = str(raw.get("day_of_week") or raw.get("day") or "").strip().title() - try: - start_h, end_h = int(raw.get("start_hour")), int(raw.get("end_hour")) - start_m, end_m = int(raw.get("start_minute") or 0), int(raw.get("end_minute") or 0) - except (TypeError, ValueError): - errors.append(f"ad_schedule[{i}] hours and minutes must be whole numbers.") - continue - if day not in DAYS: - errors.append(f"ad_schedule[{i}].day_of_week must be one of {list(DAYS)}, got '{raw.get('day_of_week') or raw.get('day')}'.") - if not (0 <= start_h <= 23 and 0 <= end_h <= 24) or (end_h == 24 and end_m): - errors.append(f"ad_schedule[{i}] hours are 0–23 to start and 0–24 to end (24 only with minute 0).") - if start_m not in _MINUTES or end_m not in _MINUTES: - errors.append(f"ad_schedule[{i}] minutes are 0, 15, 30 or 45.") - if (end_h, end_m) <= (start_h, start_m): - errors.append(f"ad_schedule[{i}] must end after it starts.") - blocks.append({"Day": day, "FromHour": start_h, "FromMinute": _MINUTES.get(start_m, "Zero"), - "ToHour": end_h, "ToMinute": _MINUTES.get(end_m, "Zero")}) - by_day: dict[str, list] = {} - for b in blocks: - by_day.setdefault(b["Day"], []).append(b) - for day, items in by_day.items(): - minutes = sorted((b["FromHour"] * 60 + list(_MINUTES.values()).index(b["FromMinute"]) * 15, - b["ToHour"] * 60 + list(_MINUTES.values()).index(b["ToMinute"]) * 15) for b in items) - if any(a[1] > b[0] for a, b in zip(minutes, minutes[1:])): - errors.append(f"ad_schedule windows on {day} overlap.") - if len(items) > _MAX_WINDOWS_PER_DAY: - errors.append(f"At most {_MAX_WINDOWS_PER_DAY} ad_schedule windows on {day} (Microsoft's limit).") - return blocks - - -# Microsoft: "the maximum number of day and time criteria per day that you -# can set is seven" (per campaign or ad group; DayTimeCriterion reference). -_MAX_WINDOWS_PER_DAY = 7 - - -def _block_span(b: dict) -> tuple[str, int, int]: - """(day, start minute, end minute) of a DayTime window.""" - rev = {v: k for k, v in _MINUTES.items()} - return (str(b.get("Day")), int(b.get("FromHour") or 0) * 60 + rev.get(b.get("FromMinute"), 0), - int(b.get("ToHour") or 0) * 60 + rev.get(b.get("ToMinute"), 0)) - - -def _schedule_steps(current: list[dict], blocks: list[dict], campaign_id: str) -> dict: - """Order a schedule replacement the way Microsoft allows it. - - A DayTime window cannot be edited, only deleted and added, and windows - in a campaign must not overlap. Unchanged windows stay; new windows that - overlap none of today's go in first; then the old ones are deleted; then - the remaining new ones are added. ``gap`` is True when, between the last - two steps, the campaign has no window at all (it then serves at all hours). - """ - old = {_block_span(c): c for c in current} - new = {_block_span(b): b for b in blocks} - keep = set(old) & set(new) - remove = [old[s]["criterion_id"] for s in old if s not in keep] - to_add = [new[s] for s in new if s not in keep] - - def overlaps(span: tuple[str, int, int]) -> bool: - return any(o[0] == span[0] and span[1] < o[2] and o[1] < span[2] for o in old if o not in keep) - - def item(b: dict) -> dict: - return {"Type": "BiddableCampaignCriterion", "CampaignId": campaign_id, - "Criterion": {"Type": "DayTimeCriterion", **b}, - "CriterionBid": {"Type": "BidMultiplier", "Multiplier": 0}} - - # Before the deletes, a day still holds all of today's windows, and - # Microsoft allows at most seven per day: add early only what fits. - room = {} - for span in old: - room[span[0]] = room.get(span[0], _MAX_WINDOWS_PER_DAY) - 1 - first, after = [], [] - for b in to_add: - span = _block_span(b) - if not overlaps(span) and room.get(span[0], _MAX_WINDOWS_PER_DAY) > 0: - room[span[0]] = room.get(span[0], _MAX_WINDOWS_PER_DAY) - 1 - first.append(item(b)) - else: - after.append(item(b)) - return {"schedule_add_first": first, "schedule_delete": remove, "schedule_add_after": after, - "schedule_kept": [_block_label(old[s]) for s in old if s in keep], - "gap": bool(after) and not keep and not first} - - -def _block_label(b: dict) -> str: - rev = {v: k for k, v in _MINUTES.items()} - return f"{b['Day'][:3]} {b['FromHour']:02d}:{rev.get(b['FromMinute'], 0):02d}–{b['ToHour']:02d}:{rev.get(b['ToMinute'], 0):02d}" - - -def update_microsoft_campaign_targeting( - config: AdLoopConfig, - *, - ad_account_id: str = "", - campaign_id: str = "", - location_ids: list[str] | None = None, - excluded_location_ids: list[str] | None = None, - location_intent: str = "", - ad_schedule: list[dict] | None = None, -) -> dict: - """Draft targeting changes: included and excluded locations, location intent, ad schedule.""" - operation = "microsoft_update_targeting" - blocked = _guard(operation, config) - if blocked: - return blocked - errors: list[str] = [] - campaign_id = str(campaign_id or "").strip() - if not campaign_id: - errors.append("campaign_id is required") - include = _clean(location_ids) if location_ids is not None else None - exclude = _clean(excluded_location_ids) if excluded_location_ids is not None else None - if include is not None and not include: - errors.append("An empty location list would let the campaign serve everywhere; pass at least one location id.") - if include and exclude and set(include) & set(exclude): - errors.append(f"Location(s) {sorted(set(include) & set(exclude))} cannot be both included and excluded.") - bad_ids = [i for i in (include or []) + (exclude or []) if not i.isdigit()] - if bad_ids: - errors.append(f"Location ids are numbers (search_microsoft_locations); got {bad_ids}.") - intent = (location_intent or "").strip() - if intent and intent not in INTENTS: - errors.append(f"location_intent must be one of {list(INTENTS)}.") - blocks = _schedule_blocks(ad_schedule, errors) if ad_schedule is not None else None - if errors: - return _validation_error(errors) - if include is None and exclude is None and not intent and blocks is None: - return {"error": "Nothing to change: pass location_ids, excluded_location_ids, location_intent or ad_schedule."} - meta, account, customer = _ctx(config, ad_account_id) - found = find_entity(config, account, customer, "campaign", campaign_id) - if not found: - return {"error": f"Microsoft campaign '{campaign_id}' was not found in account {account}."} - campaign = found["entity"] - current = _current_targeting(config, account, customer, campaign_id) - names: dict[str, str] = {} - try: - from adloop.microsoft_ads.read import _GEO_CACHE, location_names - - if _GEO_CACHE.get("rows"): - names = location_names(_GEO_CACHE["rows"], (include or []) + (exclude or [])) - except Exception: # noqa: BLE001 — names are a convenience - names = {} - label = lambda i: names.get(i) or current["included"].get(i, {}).get("name") or current["excluded"].get(i, {}).get("name") or f"id {i}" # noqa: E731 - plan_ops: dict[str, Any] = {"add": [], "delete": [], "update": [], - "schedule_add_first": [], "schedule_delete": [], "schedule_add_after": []} - shown: dict[str, Any] = {} - warnings: list[str] = [] - if include is not None: - add = [i for i in include if i not in current["included"]] - drop = [current["included"][i]["criterion_id"] for i in current["included"] if i not in include] - plan_ops["add"] += [{"Type": "BiddableCampaignCriterion", "CampaignId": campaign_id, - "Criterion": {"Type": "LocationCriterion", "LocationId": int(i)}, - "CriterionBid": {"Type": "BidMultiplier", "Multiplier": 0}} for i in add] - plan_ops["delete"] += drop - shown["locations"] = {"from": [v["name"] for v in current["included"].values()], - "to": [label(i) for i in include], "added": [label(i) for i in add], - "removed": [current["included"][i]["name"] for i in current["included"] if i not in include]} - if exclude is not None: - add = [i for i in exclude if i not in current["excluded"]] - drop = [current["excluded"][i]["criterion_id"] for i in current["excluded"] if i not in exclude] - plan_ops["add"] += [{"Type": "NegativeCampaignCriterion", "CampaignId": campaign_id, - "Criterion": {"Type": "LocationCriterion", "LocationId": int(i)}} for i in add] - plan_ops["delete"] += drop - shown["excluded_locations"] = {"from": [v["name"] for v in current["excluded"].values()], - "to": [label(i) for i in exclude]} - if intent and intent != (current["intent"] or {}).get("option"): - item = {"Type": "BiddableCampaignCriterion", "CampaignId": campaign_id, - "Criterion": {"Type": "LocationIntentCriterion", "IntentOption": intent}} - if current["intent"]: - plan_ops["update"].append({**item, "Id": current["intent"]["criterion_id"]}) - else: - plan_ops["add"].append(item) - shown["location_intent"] = {"from": (current["intent"] or {}).get("option") or "PeopleInOrSearchingForOrViewingPages (default)", - "to": intent} - if intent != "PeopleIn": - warnings.append("This intent also reaches people outside the locations who search for or about them.") - if blocks is not None: - steps = _schedule_steps(current["schedule"], blocks, campaign_id) - gap = steps.pop("gap") - plan_ops.update(steps) - # The campaign decides whose clock the hours follow. - searcher_time = bool(campaign.get("AdScheduleUseSearcherTimeZone")) - current["searcher_time_zone"] = searcher_time - zone = "each searcher's own time zone" if searcher_time else f"the account time zone ({meta['time_zone']})" - shown["ad_schedule"] = {"from": [_block_label(b) for b in current["schedule"]] or "all hours", - "to": [_block_label(b) for b in blocks] or "all hours", - "hours_in": zone} - if searcher_time: - warnings.append("This campaign runs its ad schedule in each searcher's own time zone " - "(AdScheduleUseSearcherTimeZone), not the account's: 09:00 means 09:00 where the searcher is.") - else: - warnings.append(f"Ad schedule hours are in the account time zone ({meta['time_zone']}), not the searcher's.") - if blocks and not current["schedule"]: - warnings.append("The campaign serves at all hours today; this schedule switches every other hour off.") - if gap: - warnings.append("Microsoft cannot edit a schedule window, only delete and add one, and windows may not " - "overlap: the old windows are removed before the new ones are added, so for a moment " - "the campaign has no schedule and serves at all hours. If adding the new windows then " - "fails, the apply reports it (PARTIAL_APPLY) and the campaign stays unscheduled until " - "the schedule is added again.") - if not any(v for k, v in plan_ops.items() if k != "schedule_kept"): - return {"error": "Nothing to change: the targeting already matches."} - return _plan( - operation, "campaign", campaign_id, account, customer, - {"entity_name": campaign.get("Name"), "changes": shown}, - {"operations": plan_ops, "before": current}, - warnings=warnings, - double=bool(blocks) and not current["schedule"], - ) - - -# --------------------------------------------------------------------------- -# New campaign -# --------------------------------------------------------------------------- - - -def draft_microsoft_campaign( - config: AdLoopConfig, - *, - ad_account_id: str = "", - name: str = "", - daily_budget: float = 0.0, - bidding_strategy: str = "MaxConversions", - target_cpa: float | None = None, - languages: list[str] | None = None, - location_ids: list[str] | None = None, - excluded_location_ids: list[str] | None = None, - location_intent: str = "PeopleIn", - tracking_url_template: str = "", - final_url_suffix: str = "", -) -> dict: - """Draft a new Search campaign, created PAUSED, with its locations and location intent.""" - from adloop.safety.guards import SafetyViolation, check_budget_cap - - operation = "microsoft_create_campaign" - blocked = _guard(operation, config) - if blocked: - return blocked - errors: list[str] = [] - name = (name or "").strip() - if not name or len(name) > 128: - errors.append("name is required (at most 128 characters).") - try: - budget = round(float(daily_budget), 2) - except (TypeError, ValueError): - budget = 0.0 - if budget <= 0: - errors.append("daily_budget must be a positive amount in the account currency.") - strategy = "MaxConversions" if bidding_strategy == "TargetCpa" else (bidding_strategy or "MaxConversions") - if strategy not in STRATEGIES: - errors.append(f"bidding_strategy must be one of {list(STRATEGIES)}.") - if target_cpa is not None and strategy != "MaxConversions": - errors.append(f"target_cpa goes with MaxConversions, not {strategy}.") - langs = _clean(languages) - if not langs: - errors.append("languages is required, e.g. ['English']: without it ads reach every language.") - elif any(lang.lower() == "all" for lang in langs): - errors.append("languages=['All'] reaches every language; name the languages the ads are written in, " - "e.g. ['English'].") - include = _clean(location_ids) - if not include: - errors.append("location_ids is required (search_microsoft_locations): an untargeted campaign serves everywhere.") - exclude = _clean(excluded_location_ids) - if any(not i.isdigit() for i in include + exclude): - errors.append("Location ids are numbers (search_microsoft_locations).") - if location_intent not in INTENTS: - errors.append(f"location_intent must be one of {list(INTENTS)}.") - if errors: - return _validation_error(errors) - try: - check_budget_cap(budget, config.safety) - except SafetyViolation as e: - return {"error": str(e)} - meta, account, customer = _ctx(config, ad_account_id) - existing = {str(c.get("Name")).lower() for c in _campaigns(config, account, customer)} - if name.lower() in existing: - return _validation_error([f"A campaign named '{name}' already exists."]) - warnings: list[str] = [] - if strategy in _CONVERSION_BASED: - goals = _counted_goals(config, account, customer) - if goals == 0: - return _validation_error([_no_goal_refusal(strategy)]) - if goals < 0: - warnings.append(_goals_unknown_warning(strategy)) - if target_cpa is not None and target_cpa > 0 and budget < 5 * target_cpa: - warnings.append(f"A daily budget below 5× the target CPA ({target_cpa}) gives bidding little to learn from.") - campaign: dict[str, Any] = { - "Name": name, - "BudgetType": "DailyBudgetStandard", - "DailyBudget": budget, - "CampaignType": "Search", - "Languages": langs, - "Status": "Paused", - "TimeZone": meta["time_zone"], - "BiddingScheme": bidding_scheme(strategy, target_cpa=target_cpa, max_cpc=None), - } - if tracking_url_template: - campaign["TrackingUrlTemplate"] = tracking_url_template.strip() - if final_url_suffix: - campaign["FinalUrlSuffix"] = final_url_suffix.strip() - criteria = ( - [{"Type": "BiddableCampaignCriterion", "Criterion": {"Type": "LocationCriterion", "LocationId": int(i)}, - "CriterionBid": {"Type": "BidMultiplier", "Multiplier": 0}} for i in include] - + [{"Type": "NegativeCampaignCriterion", "Criterion": {"Type": "LocationCriterion", "LocationId": int(i)}} - for i in exclude] - + [{"Type": "BiddableCampaignCriterion", - "Criterion": {"Type": "LocationIntentCriterion", "IntentOption": location_intent}}] - ) - # [AUD]: search campaigns reach the Microsoft Audience Network (Outlook, - # MSN) unless their AudienceAdsBidAdjustment is -100. - warnings.append("New search campaigns can also show on the Microsoft Audience Network (Outlook, MSN, Edge); " - "set audience_ads_bid_adjustment=-100 on its ad groups (update_microsoft_ad_group) to keep " - "it on search only.") - return _plan( - operation, "campaign", "", account, customer, - { - "entity_name": name, "status_on_create": "Paused", "daily_budget": budget, "currency": meta["currency"], - "monthly_maximum": round(budget * 30.4, 2), "bidding": _bidding(campaign["BiddingScheme"]), - "languages": langs, "location_ids": include, "excluded_location_ids": exclude or None, - "location_intent": location_intent, "time_zone": meta["time_zone"], - "tracking_url_template": campaign.get("TrackingUrlTemplate"), - "final_url_suffix": campaign.get("FinalUrlSuffix"), - }, - {"campaign": campaign, "criteria": criteria}, - warnings=warnings + [ - "Created paused. Add ad groups, keywords, ads and extensions, then enable it.", - ], - ) - - -# --------------------------------------------------------------------------- -# Ad groups and keywords -# --------------------------------------------------------------------------- - - -def _keyword_rows(keywords: list, errors: list[str], *, default_match: str = "Phrase") -> list[dict]: - rows = [] - for i, k in enumerate(keywords or []): - if isinstance(k, str): - k = {"text": k} - if not isinstance(k, dict): - errors.append(f"keywords[{i}] must be text or {{text, match_type, bid}}.") - continue - text = str(k.get("text") or "").strip() - match = str(k.get("match_type") or default_match).strip().title() - if not text or len(text) > 100: - errors.append(f"keywords[{i}] text is 1–100 characters.") - if match not in MATCH_TYPES: - errors.append(f"keywords[{i}].match_type must be one of {list(MATCH_TYPES)}.") - row: dict[str, Any] = {"Text": text, "MatchType": match, "Status": "Active"} - if k.get("bid") is not None: - row["Bid"] = {"Amount": round(float(k["bid"]), 2)} - rows.append(row) - return rows - - -def _active_broad_keywords(config, account: str, customer: str, campaign_id: str) -> list[dict]: - return [ - k for g in _ad_groups(config, account, customer, campaign_id) - for k in _keywords(config, account, customer, str(g.get("Id"))) - if k.get("MatchType") == "Broad" and k.get("Status") == "Active" - ] - - -def _check_bid(current: float | None, proposed: float | None, config) -> None: - """Bid-increase cap against the current effective bid (raises SafetyViolation).""" - from adloop.safety.guards import check_bid_increase - - if current and proposed is not None: - check_bid_increase(float(current), float(proposed), config.safety) - - -def _refuse_broad_without_conversion_bidding(rows: list[dict], campaign: dict, errors: list[str]) -> None: - strategy = _strategy_name(campaign.get("BiddingScheme")) - broad = [r["Text"] for r in rows if r["MatchType"] == "Broad"] - if broad and strategy not in _CONVERSION_BASED: - errors.append( - f"Broad match needs conversion-based bidding (MaxConversions, MaxConversionValue or a target " - f"CPA/ROAS); on a {strategy or 'manual'} campaign it buys whatever a loose match brings. Use Phrase " - f"or Exact for {broad[:5]}, or move the campaign to MaxConversions first." - ) - - -def draft_microsoft_ad_group( - config: AdLoopConfig, - *, - ad_account_id: str = "", - campaign_id: str = "", - name: str = "", - cpc_bid: float | None = None, - network: str = "OwnedAndOperatedOnly", - keywords: list | None = None, -) -> dict: - """Draft a new ad group (with optional keywords) in a campaign.""" - operation = "microsoft_create_ad_group" - blocked = _guard(operation, config) - if blocked: - return blocked - errors: list[str] = [] - name = (name or "").strip() - if not name or len(name) > 256: - errors.append("name is required (at most 256 characters).") - if network not in NETWORKS: - errors.append(f"network must be one of {list(NETWORKS)}.") - rows = _keyword_rows(keywords or [], errors) - if errors: - return _validation_error(errors) - meta, account, customer = _ctx(config, ad_account_id) - found = find_entity(config, account, customer, "campaign", str(campaign_id)) - if not found: - return {"error": f"Microsoft campaign '{campaign_id}' was not found in account {account}."} - campaign = found["entity"] - strategy = _strategy_name(campaign.get("BiddingScheme")) - if strategy in _MANUAL and cpc_bid is None: - errors.append(f"A {strategy} campaign needs cpc_bid for the ad group.") - _refuse_broad_without_conversion_bidding(rows, campaign, errors) - names = {str(g.get("Name")).lower() for g in _ad_groups(config, account, customer, str(campaign_id))} - if name.lower() in names: - errors.append(f"The campaign already has an ad group named '{name}'.") - if errors: - return _validation_error(errors) - group: dict[str, Any] = {"Name": name, "Network": network, "Status": "Active"} - if cpc_bid is not None: - group["CpcBid"] = {"Amount": round(float(cpc_bid), 2)} - warnings = ["The ad group is active but serves only once an ad in it is enabled (new ads are created paused)."] - if network == "OwnedAndOperatedAndSyndicatedSearch": - warnings.append("Syndicated search partners are included; their traffic is usually weaker.") - return _plan( - operation, "ad_group", "", account, customer, - {"entity_name": name, "campaign_name": campaign.get("Name"), "campaign_status": campaign.get("Status"), - "cpc_bid": _money(group.get("CpcBid")), "network": network, - "status_on_create": "Active (its keywords too); nothing serves until an ad in it is enabled", - "currency": meta["currency"], - "keywords": [f"{r['Text']} [{r['MatchType']}]" + (f" bid {r['Bid']['Amount']}" if r.get("Bid") else "") - for r in rows] or None}, - {"campaign_id": str(campaign_id), "ad_group": group, "keyword_rows": rows}, - warnings=warnings, - ) - - -def update_microsoft_ad_group( - config: AdLoopConfig, - *, - ad_account_id: str = "", - ad_group_id: str = "", - name: str = "", - cpc_bid: float | None = None, - network: str = "", - audience_ads_bid_adjustment: int | None = None, -) -> dict: - """Draft ad group changes: name, default bid, search network, Audience Network bid adjustment.""" - from adloop.safety.guards import SafetyViolation, check_bid_increase - - operation = "microsoft_update_ad_group" - blocked = _guard(operation, config) - if blocked: - return blocked - errors: list[str] = [] - if network and network not in NETWORKS: - errors.append(f"network must be one of {list(NETWORKS)}.") - if audience_ads_bid_adjustment is not None and not -100 <= int(audience_ads_bid_adjustment) <= 900: - errors.append("audience_ads_bid_adjustment is -100 (off) to 900.") - if errors: - return _validation_error(errors) - meta, account, customer = _ctx(config, ad_account_id) - found = find_entity(config, account, customer, "ad_group", str(ad_group_id)) - if not found: - return {"error": f"Microsoft ad group '{ad_group_id}' was not found in account {account}."} - group, campaign = found["entity"], found["campaign"] - update: dict[str, Any] = {"Id": str(ad_group_id)} - shown: dict[str, Any] = {} - touched: list[str] = [] - warnings: list[str] = [] - if name and name.strip() != group.get("Name"): - update["Name"] = name.strip() - shown["name"] = {"from": group.get("Name"), "to": name.strip()} - touched.append("Name") - if cpc_bid is not None: - old = _money(group.get("CpcBid")) - try: - if old: - check_bid_increase(old, float(cpc_bid), config.safety) - except SafetyViolation as e: - return {"error": str(e)} - update["CpcBid"] = {"Amount": round(float(cpc_bid), 2)} - shown["cpc_bid"] = {"from": old, "to": round(float(cpc_bid), 2), "currency": meta["currency"]} - touched.append("CpcBid") - if _strategy_name(campaign.get("BiddingScheme")) not in _MANUAL: - warnings.append("The campaign uses automated bidding, which ignores the ad group's default bid.") - if network and network != group.get("Network"): - update["Network"] = network - shown["network"] = {"from": group.get("Network"), "to": network} - touched.append("Network") - adjust = None - if audience_ads_bid_adjustment is not None and int(audience_ads_bid_adjustment) != group.get("AudienceAdsBidAdjustment"): - from adloop.microsoft_ads.read import audience_network - - adjust = int(audience_ads_bid_adjustment) - update["AudienceAdsBidAdjustment"] = adjust - now = audience_network(group, campaign) - was = ("off" if not now["on"] else f"{now['bid_adjustment'] or 0:+d}%") + f" (set on the {now['set_on']})" - shown["audience_network"] = {"from": was, "to": adjust, - "meaning": "off" if adjust == -100 else f"{adjust:+d}% bids on the Audience Network"} - touched.append("AudienceAdsBidAdjustment") - if len(update) == 1: - return {"error": "Nothing to change: pass at least one setting that differs from the ad group."} - return _plan( - operation, "ad_group", str(ad_group_id), account, customer, - {"entity_name": group.get("Name"), "campaign_name": campaign.get("Name"), "changes": shown}, - {"campaign_id": str(campaign.get("Id")), "update": update, "update_audience_adjustment": adjust is not None, - "before": {k: copy.deepcopy(group.get(k)) for k in sorted(set(touched))}}, - warnings=warnings, - ) - - -def draft_microsoft_keywords( - config: AdLoopConfig, *, ad_account_id: str = "", ad_group_id: str = "", keywords: list | None = None, -) -> dict: - """Draft keyword additions to an ad group (duplicates skipped, broad refused on manual bids).""" - operation = "microsoft_add_keywords" - blocked = _guard(operation, config) - if blocked: - return blocked - errors: list[str] = [] - rows = _keyword_rows(keywords or [], errors) - if not rows and not errors: - errors.append("keywords needs at least one keyword.") - if errors: - return _validation_error(errors) - meta, account, customer = _ctx(config, ad_account_id) - found = find_entity(config, account, customer, "ad_group", str(ad_group_id)) - if not found: - return {"error": f"Microsoft ad group '{ad_group_id}' was not found in account {account}."} - group, campaign = found["entity"], found["campaign"] - _refuse_broad_without_conversion_bidding(rows, campaign, errors) - if errors: - return _validation_error(errors) - existing = {(str(k.get("Text")).lower(), k.get("MatchType")) for k in _keywords(config, account, customer, str(ad_group_id)) - if k.get("Status") != "Deleted"} - seen: set = set() - new_rows, skipped = [], [] - for r in rows: - key = (r["Text"].lower(), r["MatchType"]) - if key in existing or key in seen: - skipped.append(f"{r['Text']} [{r['MatchType']}]") - continue - seen.add(key) - new_rows.append(r) - if not new_rows: - return {"error": "Every keyword is already in the ad group.", "skipped": skipped} - warnings = [f"Skipped, already in the ad group: {skipped}."] if skipped else [] - if group.get("Status") != "Active" or campaign.get("Status") != "Active": - warnings.append(f"The ad group is {group.get('Status')} and the campaign {campaign.get('Status')}: the keywords serve once both are active.") - else: - # Keywords are created Active, as Google Ads keywords are: in a live - # ad group they can serve the moment this is applied. - warnings.append("The keywords are added Active and the ad group and campaign are active, so they can serve " - "as soon as this is applied (once the ad group has an enabled ad).") - return _plan( - operation, "ad_group", str(ad_group_id), account, customer, - {"entity_name": group.get("Name"), "campaign_name": campaign.get("Name"), "status_on_create": "Active", - "ad_group_status": group.get("Status"), "campaign_status": campaign.get("Status"), - "keywords": [f"{r['Text']} [{r['MatchType']}]" + (f" bid {r['Bid']['Amount']}" if r.get("Bid") else "") - for r in new_rows]}, - {"campaign_id": str(campaign.get("Id")), "keyword_rows": new_rows}, - warnings=warnings, - ) - - -def update_microsoft_keyword_bids( - config: AdLoopConfig, *, ad_account_id: str = "", ad_group_id: str = "", bids: list | None = None, -) -> dict: - """Draft keyword bid changes in one ad group (capped by max_bid_increase_pct).""" - from adloop.safety.guards import SafetyViolation - - operation = "microsoft_update_keyword_bids" - blocked = _guard(operation, config) - if blocked: - return blocked - errors: list[str] = [] - wanted: dict[str, float | None] = {} - for i, b in enumerate(bids or []): - if not isinstance(b, dict) or not b.get("keyword_id"): - errors.append(f"bids[{i}] needs keyword_id and bid (null removes the keyword's own bid).") - continue - wanted[str(b["keyword_id"])] = None if b.get("bid") is None else round(float(b["bid"]), 2) - if not wanted and not errors: - errors.append("bids needs at least one {keyword_id, bid}.") - if errors: - return _validation_error(errors) - meta, account, customer = _ctx(config, ad_account_id) - found = find_entity(config, account, customer, "ad_group", str(ad_group_id)) - if not found: - return {"error": f"Microsoft ad group '{ad_group_id}' was not found in account {account}."} - group, campaign = found["entity"], found["campaign"] - keywords = {str(k.get("Id")): k for k in _keywords(config, account, customer, str(ad_group_id))} - missing = [k for k in wanted if k not in keywords] - if missing: - return _validation_error([f"Keyword(s) {missing} are not in ad group '{group.get('Name')}'."]) - default_bid = _money(group.get("CpcBid")) - rows, shown, before = [], [], {} - for kid, bid in wanted.items(): - current = _money(keywords[kid].get("Bid")) or default_bid - # Removing a keyword's own bid makes it inherit the ad group default: - # that is a bid change too, and it is capped the same way. - effective = bid if bid is not None else default_bid - try: - _check_bid(current, effective, config) - except SafetyViolation as e: - return {"error": f"{keywords[kid].get('Text')}: {e}"} - rows.append({"Id": kid, "Bid": {"Amount": bid}}) - shown.append({"keyword": f"{keywords[kid].get('Text')} [{keywords[kid].get('MatchType')}]", - "from": current, "to": bid if bid is not None else f"ad group default {default_bid}"}) - before[kid] = copy.deepcopy(keywords[kid].get("Bid")) - return _plan( - operation, "ad_group", str(ad_group_id), account, customer, - {"entity_name": group.get("Name"), "currency": meta["currency"], "bids": shown}, - {"campaign_id": str(campaign.get("Id")), "keyword_rows": rows, "before": before, - "default_bid_before": copy.deepcopy(group.get("CpcBid"))}, - ) - - -# --------------------------------------------------------------------------- -# Negative keywords: direct and shared lists -# --------------------------------------------------------------------------- - - -def _negative_rows(keywords: list, match_type: str, errors: list[str]) -> list[dict]: - match = (match_type or "Phrase").strip().title() - if match not in NEGATIVE_MATCH_TYPES: - errors.append(f"match_type for negatives must be one of {list(NEGATIVE_MATCH_TYPES)}.") - rows, seen = [], set() - for text in _clean(keywords): - if len(text) > 100: - errors.append(f"Negative '{text[:20]}…' is longer than 100 characters.") - if text.lower() not in seen: - seen.add(text.lower()) - rows.append({"Text": text, "MatchType": match}) - if not rows and not errors: - errors.append("keywords needs at least one negative keyword.") - return rows - - -def _entity_negatives(config: AdLoopConfig, account: str, customer: str, entity_type: str, entity_id: str, - parent_id: str = "") -> list[dict]: - payload = campaign_request( - config, "NegativeKeywords/QueryByEntityIds", - {"EntityIds": [int(entity_id)], "EntityType": entity_type, "ParentEntityId": int(parent_id) if parent_id else None}, - account_id=account, customer_id=customer, - ) - out = [] - for entry in payload.get("EntityNegativeKeywords") or []: - out.extend(n for n in (entry or {}).get("NegativeKeywords") or [] if isinstance(n, dict)) - return out - - -def _shared_lists(config: AdLoopConfig, account: str, customer: str) -> list[dict]: - payload = campaign_request( - config, "SharedEntities/Query", {"SharedEntityType": _LIST_TYPE, "SharedEntityScope": "Account"}, - account_id=account, customer_id=customer, - ) - return [e for e in payload.get("SharedEntities") or [] if isinstance(e, dict)] - - -def _list_items(config: AdLoopConfig, account: str, customer: str, list_id: str) -> list[dict]: - payload = campaign_request( - config, "ListItems/QueryBySharedList", - {"SharedList": {"Type": _LIST_TYPE, "Id": int(list_id)}, "SharedEntityScope": "Account"}, - account_id=account, customer_id=customer, - ) - return [i for i in payload.get("ListItems") or [] if isinstance(i, dict)] - - -def _list_associations(config: AdLoopConfig, account: str, customer: str, campaign_ids: list[str]) -> list[dict]: - out = [] - for chunk in _chunks([int(c) for c in campaign_ids]): - payload = campaign_request( - config, "SharedEntityAssociations/QueryByEntityIds", - {"EntityIds": chunk, "EntityType": "Campaign", "SharedEntityType": _LIST_TYPE, "SharedEntityScope": "Account"}, - account_id=account, customer_id=customer, - ) - out.extend(a for a in payload.get("Associations") or [] if isinstance(a, dict)) - return out - - -def _positive_conflicts(config: AdLoopConfig, account: str, customer: str, campaign_ids: list[str], rows: list[dict]) -> list[str]: - texts = {r["Text"].lower(): r for r in rows} - hits = [] - for cid in campaign_ids: - for g in _ad_groups(config, account, customer, cid): - for k in _keywords(config, account, customer, str(g.get("Id"))): - text = str(k.get("Text") or "").lower() - if k.get("Status") == "Active" and text in texts: - hits.append(f"'{k.get('Text')}' ({g.get('Name')})") - return hits - - -def get_microsoft_negative_keywords(config: AdLoopConfig, *, ad_account_id: str = "", campaign_id: str = "") -> dict: - """Negative keywords of the account's campaigns: direct ones and shared lists with their items.""" - meta, account, customer = _ctx(config, ad_account_id) - campaigns = [c for c in _campaigns(config, account, customer) if not campaign_id or str(c.get("Id")) == str(campaign_id)] - direct = [] - for c in campaigns: - for n in _entity_negatives(config, account, customer, "Campaign", str(c.get("Id"))): - direct.append({"campaign_id": str(c.get("Id")), "campaign_name": c.get("Name"), "text": n.get("Text"), - "match_type": n.get("MatchType"), - "remove_id": f"Campaign~{c.get('Id')}~{n.get('Id')}"}) - lists = _shared_lists(config, account, customer) - associations = _list_associations(config, account, customer, [str(c.get("Id")) for c in campaigns]) if campaigns else [] - names = {str(c.get("Id")): c.get("Name") for c in campaigns} - attached: dict[str, list[str]] = {} - for a in associations: - attached.setdefault(str(a.get("SharedEntityId")), []).append(names.get(str(a.get("EntityId")), str(a.get("EntityId")))) - shared = [] - for lst in lists: - lid = str(lst.get("Id")) - if campaign_id and lid not in attached: - continue - items = _list_items(config, account, customer, lid) - shared.append({ - "list_id": lid, "name": lst.get("Name"), "item_count": lst.get("ItemCount", len(items)), - "attached_to": attached.get(lid, []), - "keywords": [{"text": i.get("Text"), "match_type": i.get("MatchType"), "remove_id": f"{lid}~{i.get('Id')}"} - for i in items], - }) - insights = [] - if direct: - insights.append(f"{len(direct)} negative(s) sit directly on campaigns; a shared list keeps them reusable across campaigns.") - unattached = [s["name"] for s in shared if not s["attached_to"]] - if unattached and not campaign_id: - insights.append(f"Lists attached to no campaign: {unattached}.") - return {"ad_account_id": account, "direct_negatives": direct, "negative_keyword_lists": shared, "insights": insights} - - -def add_microsoft_negative_keywords( - config: AdLoopConfig, *, ad_account_id: str = "", campaign_id: str = "", ad_group_id: str = "", - keywords: list | None = None, match_type: str = "Phrase", -) -> dict: - """Draft negatives directly on one campaign or ad group.""" - operation = "microsoft_add_negative_keywords" - blocked = _guard(operation, config) - if blocked: - return blocked - errors: list[str] = [] - if bool(campaign_id) == bool(ad_group_id): - errors.append("Pass exactly one of campaign_id or ad_group_id.") - rows = _negative_rows(keywords or [], match_type, errors) - if errors: - return _validation_error(errors) - meta, account, customer = _ctx(config, ad_account_id) - kind = "campaign" if campaign_id else "ad_group" - found = find_entity(config, account, customer, kind, str(campaign_id or ad_group_id)) - if not found: - return {"error": f"Microsoft {kind.replace('_', ' ')} '{campaign_id or ad_group_id}' was not found."} - entity, campaign = found["entity"], found["campaign"] - entity_type = "Campaign" if kind == "campaign" else "AdGroup" - existing = {(str(n.get("Text")).lower(), n.get("MatchType")) for n in _entity_negatives( - config, account, customer, entity_type, str(entity.get("Id")), "" if kind == "campaign" else str(campaign.get("Id")))} - new_rows = [r for r in rows if (r["Text"].lower(), r["MatchType"]) not in existing] - if not new_rows: - return {"error": "Every negative is already there."} - warnings = ["A shared negative keyword list (propose_microsoft_negative_keyword_list) keeps negatives reusable across campaigns."] - conflicts = _positive_conflicts(config, account, customer, [str(campaign.get("Id"))], new_rows) - if conflicts: - warnings.append(f"These negatives block active keywords: {conflicts[:10]}.") - return _plan( - operation, kind, str(entity.get("Id")), account, customer, - {"entity_name": entity.get("Name"), - "campaign_name": campaign.get("Name") if kind == "ad_group" else None, - "negatives": [f"{r['Text']} [{r['MatchType']}]" for r in new_rows]}, - {"entity_kind": entity_type, "campaign_id": str(campaign.get("Id")), "negative_rows": new_rows}, - warnings=warnings, - ) - - -def propose_microsoft_negative_keyword_list( - config: AdLoopConfig, *, ad_account_id: str = "", list_name: str = "", keywords: list | None = None, - match_type: str = "Phrase", campaign_ids: list[str] | None = None, -) -> dict: - """Draft a new shared negative keyword list and attach it to campaigns.""" - operation = "microsoft_create_negative_list" - blocked = _guard(operation, config) - if blocked: - return blocked - errors: list[str] = [] - list_name = (list_name or "").strip() - if not list_name or len(list_name) > 255: - errors.append("list_name is required (at most 255 characters).") - rows = _negative_rows(keywords or [], match_type, errors) - if len(rows) > 5000: - errors.append("At most 5,000 negatives in one draft.") - cids = _clean(campaign_ids) - if errors: - return _validation_error(errors) - meta, account, customer = _ctx(config, ad_account_id) - if list_name.lower() in {str(lst.get("Name")).lower() for lst in _shared_lists(config, account, customer)}: - return _validation_error([f"A negative keyword list named '{list_name}' already exists; add_to_microsoft_negative_keyword_list appends to it."]) - campaigns = {str(c.get("Id")): c for c in _campaigns(config, account, customer)} - unknown = [c for c in cids if c not in campaigns] - if unknown: - return _validation_error([f"Campaign(s) {unknown} are not in account {account}."]) - warnings = [] - if cids: - counts: dict[str, int] = {} - for a in _list_associations(config, account, customer, cids): - counts[str(a.get("EntityId"))] = counts.get(str(a.get("EntityId")), 0) + 1 - full = [campaigns[c].get("Name") for c in cids if counts.get(c, 0) >= _MAX_LISTS_PER_CAMPAIGN] - if full: - return _validation_error([f"Campaign(s) {full} already have {_MAX_LISTS_PER_CAMPAIGN} lists, Microsoft's limit."]) - conflicts = _positive_conflicts(config, account, customer, cids, rows) - if conflicts: - warnings.append(f"These negatives block active keywords: {conflicts[:10]}.") - else: - warnings.append("The list is attached to no campaign, so it blocks nothing until attached.") - return _plan( - operation, "negative_keyword_list", "", account, customer, - {"entity_name": list_name, "negatives": [f"{r['Text']} [{r['MatchType']}]" for r in rows], - "attach_to": [campaigns[c].get("Name") for c in cids]}, - {"campaign_ids": cids, "negative_rows": rows}, - warnings=warnings, - ) - - -def add_to_microsoft_negative_keyword_list( - config: AdLoopConfig, *, ad_account_id: str = "", list_id: str = "", keywords: list | None = None, - match_type: str = "Phrase", -) -> dict: - """Draft appending negatives to an existing shared list (items already there are skipped).""" - operation = "microsoft_add_to_negative_list" - blocked = _guard(operation, config) - if blocked: - return blocked - errors: list[str] = [] - rows = _negative_rows(keywords or [], match_type, errors) - if errors: - return _validation_error(errors) - meta, account, customer = _ctx(config, ad_account_id) - lists = {str(lst.get("Id")): lst for lst in _shared_lists(config, account, customer)} - if str(list_id) not in lists: - return {"error": f"Negative keyword list '{list_id}' was not found (get_microsoft_negative_keywords lists them)."} - items = _list_items(config, account, customer, str(list_id)) - have = {(str(i.get("Text")).lower(), i.get("MatchType")) for i in items} - new_rows = [r for r in rows if (r["Text"].lower(), r["MatchType"]) not in have] - if not new_rows: - return {"error": "Every negative is already in the list."} - attached = [str(a.get("EntityId")) for a in _list_associations( - config, account, customer, [str(c.get("Id")) for c in _campaigns(config, account, customer)]) - if str(a.get("SharedEntityId")) == str(list_id)] - warnings = [] - conflicts = _positive_conflicts(config, account, customer, attached, new_rows) - if conflicts: - warnings.append(f"These negatives block active keywords: {conflicts[:10]}.") - return _plan( - operation, "negative_keyword_list", str(list_id), account, customer, - {"entity_name": lists[str(list_id)].get("Name"), "attached_campaigns": len(attached), - "negatives": [f"{r['Text']} [{r['MatchType']}]" for r in new_rows]}, - {"negative_rows": new_rows}, - warnings=warnings, - ) - - -def _draft_list_link(config, *, attach: bool, ad_account_id: str, list_id: str, campaign_ids: list | None) -> dict: - operation = "microsoft_attach_negative_list" if attach else "microsoft_detach_negative_list" - blocked = _guard(operation, config) - if blocked: - return blocked - cids = _clean(campaign_ids) - if not cids: - return _validation_error(["campaign_ids needs at least one campaign id."]) - meta, account, customer = _ctx(config, ad_account_id) - lists = {str(lst.get("Id")): lst for lst in _shared_lists(config, account, customer)} - if str(list_id) not in lists: - return {"error": f"Negative keyword list '{list_id}' was not found."} - campaigns = {str(c.get("Id")): c for c in _campaigns(config, account, customer)} - unknown = [c for c in cids if c not in campaigns] - if unknown: - return _validation_error([f"Campaign(s) {unknown} are not in account {account}."]) - linked = {str(a.get("EntityId")) for a in _list_associations(config, account, customer, cids) - if str(a.get("SharedEntityId")) == str(list_id)} - targets = [c for c in cids if (c not in linked) == attach] - if not targets: - return {"error": "Nothing to change: every campaign is already " + ("attached." if attach else "detached.")} - warnings = [] - if not attach: - warnings.append("Detached campaigns stop blocking these negatives; the list itself stays.") - return _plan( - operation, "negative_keyword_list", str(list_id), account, customer, - {"entity_name": lists[str(list_id)].get("Name"), "campaigns": [campaigns[c].get("Name") for c in targets]}, - {"campaign_ids": targets}, - warnings=warnings, - ) - - -def attach_microsoft_negative_keyword_list(config, *, ad_account_id="", list_id="", campaign_ids=None) -> dict: - return _draft_list_link(config, attach=True, ad_account_id=ad_account_id, list_id=list_id, campaign_ids=campaign_ids) - - -def detach_microsoft_negative_keyword_list(config, *, ad_account_id="", list_id="", campaign_ids=None) -> dict: - return _draft_list_link(config, attach=False, ad_account_id=ad_account_id, list_id=list_id, campaign_ids=campaign_ids) - - -# --------------------------------------------------------------------------- -# Responsive search ads -# --------------------------------------------------------------------------- - - -def _assets(items: list, limit: int, slots: tuple, field: str, errors: list[str]) -> list[dict]: - links = [] - for i, item in enumerate(items or []): - text, pin = (item.get("text"), item.get("pinned_field")) if isinstance(item, dict) else (item, None) - text = str(text or "").strip() - if not text or len(text) > limit: - errors.append(f"{field}[{i}] is 1–{limit} characters (got {len(text)}): '{text}'.") - link: dict[str, Any] = {"Asset": {"Type": "TextAsset", "Text": text}} - if pin: - normalized = _PINS.get(str(pin).strip().lower().replace(" ", "_")) - if normalized not in slots: - errors.append(f"{field}[{i}].pinned_field must be one of {list(slots)}.") - link["PinnedField"] = normalized - links.append(link) - texts = [l["Asset"]["Text"].lower() for l in links] - if len(set(texts)) != len(texts): - errors.append(f"{field} repeat the same text.") - for slot in slots: - pinned = [l for l in links if l.get("PinnedField") == slot] - unpinned = [l for l in links if not l.get("PinnedField")] - if not pinned and not unpinned: - errors.append(f"Nothing can fill {slot}: pin an asset there or leave some unpinned.") - return links - - -def _rsa_fields(headlines, descriptions, final_url, path1, path2, errors, warnings, *, partial: bool) -> dict: - fields: dict[str, Any] = {} - if headlines is not None or not partial: - h = _assets(headlines or [], 30, ("Headline1", "Headline2", "Headline3"), "headlines", errors) - if not 3 <= len(h) <= 15: - errors.append(f"An RSA takes 3–15 headlines (got {len(h)}).") - fields["Headlines"] = h - if descriptions is not None or not partial: - d = _assets(descriptions or [], 90, ("Description1", "Description2"), "descriptions", errors) - if not 2 <= len(d) <= 4: - errors.append(f"An RSA takes 2–4 descriptions (got {len(d)}).") - fields["Descriptions"] = d - if final_url or not partial: - _check_url((final_url or "").strip(), errors, warnings) - fields["FinalUrls"] = [(final_url or "").strip()] - for name, value in (("Path1", path1), ("Path2", path2)): - if value is None: - continue - value = value.strip() - if len(value) > 15 or "/" in value: - errors.append(f"{name.lower()} is at most 15 characters, without '/'.") - fields[name] = value - if fields.get("Path2") and not (fields.get("Path1") or (partial and path1 is None)): - errors.append("path2 needs path1.") - if not partial and fields.get("Headlines") and len(fields["Headlines"]) < 8: - warnings.append("8–15 distinct headlines give Microsoft more combinations to test.") - pins = [l for l in fields.get("Headlines", []) + fields.get("Descriptions", []) if l.get("PinnedField")] - if pins: - warnings.append(f"{len(pins)} asset(s) are pinned; pinning limits the combinations Microsoft can show.") - return fields - - -def draft_microsoft_responsive_search_ad( - config: AdLoopConfig, *, ad_account_id: str = "", ad_group_id: str = "", headlines: list | None = None, - descriptions: list | None = None, final_url: str = "", path1: str = "", path2: str = "", -) -> dict: - """Draft a responsive search ad, created PAUSED.""" - operation = "microsoft_create_rsa" - blocked = _guard(operation, config) - if blocked: - return blocked - errors: list[str] = [] - warnings: list[str] = [] - fields = _rsa_fields(headlines, descriptions, final_url, path1, path2, errors, warnings, partial=False) - if errors: - return _validation_error(errors) - meta, account, customer = _ctx(config, ad_account_id) - found = find_entity(config, account, customer, "ad_group", str(ad_group_id)) - if not found: - return {"error": f"Microsoft ad group '{ad_group_id}' was not found in account {account}."} - group, campaign = found["entity"], found["campaign"] - ad = {"Type": "ResponsiveSearch", "Status": "Paused", **fields} - for key in ("Path1", "Path2"): - if not ad.get(key): - ad.pop(key, None) - if "Path1" not in ad: - ad.pop("Path2", None) - warnings.append("No display paths: path1/path2 make the display URL more specific.") - return _plan( - operation, "ad_group", str(ad_group_id), account, customer, - {"entity_name": group.get("Name"), "campaign_name": campaign.get("Name"), "status_on_create": "Paused", - "headlines": [l["Asset"]["Text"] + (f" [pinned {l['PinnedField']}]" if l.get("PinnedField") else "") - for l in fields["Headlines"]], - "descriptions": [l["Asset"]["Text"] for l in fields["Descriptions"]], - "final_url": fields["FinalUrls"][0], "path1": ad.get("Path1"), "path2": ad.get("Path2")}, - {"campaign_id": str(campaign.get("Id")), "ad": ad}, - warnings=warnings, - ) - - -def update_microsoft_responsive_search_ad( - config: AdLoopConfig, *, ad_account_id: str = "", ad_id: str = "", headlines: list | None = None, - descriptions: list | None = None, final_url: str = "", path1: str | None = None, path2: str | None = None, -) -> dict: - """Draft RSA changes: headlines or descriptions (each list replaced whole), landing page, paths.""" - operation = "microsoft_update_rsa" - blocked = _guard(operation, config) - if blocked: - return blocked - errors: list[str] = [] - warnings: list[str] = [] - fields = _rsa_fields(headlines, descriptions, final_url, path1, path2, errors, warnings, partial=True) - if errors: - return _validation_error(errors) - if not fields: - return {"error": "Nothing to change: pass headlines, descriptions, final_url, path1 or path2."} - meta, account, customer = _ctx(config, ad_account_id) - found = find_entity(config, account, customer, "ad", str(ad_id)) - if not found: - return {"error": f"Microsoft ad '{ad_id}' was not found in account {account}."} - ad, group, campaign = found["entity"], found["ad_group"], found["campaign"] - if ad.get("Type") != "ResponsiveSearch": - return _validation_error([f"Ad {ad_id} is a {ad.get('Type')} ad; only responsive search ads are edited here."]) - shown = {} - for key, value in fields.items(): - if key in ("Headlines", "Descriptions"): - shown[key.lower()] = {"from": [l.get("Asset", {}).get("Text") for l in ad.get(key) or []], - "to": [l["Asset"]["Text"] for l in value]} - else: - shown[key.lower()] = {"from": ad.get(key), "to": value} - warnings.append("Edited ads go back to Microsoft's editorial review.") - return _plan( - operation, "ad", str(ad_id), account, customer, - {"entity_name": f"RSA {ad_id}", "ad_group_name": group.get("Name"), "campaign_name": campaign.get("Name"), - "changes": shown}, - {"campaign_id": str(campaign.get("Id")), "ad_group_id": str(group.get("Id")), - "update": {"Type": "ResponsiveSearch", "Id": str(ad_id), **fields}, - "before": {k: copy.deepcopy(ad.get(k)) for k in fields}}, - warnings=warnings, - ) - - -# --------------------------------------------------------------------------- -# Ad extensions: sitelinks, callouts, structured snippets, call -# --------------------------------------------------------------------------- - -# The plan's entity_type for each Microsoft AssociationType. -_ASSOCIATION_ENTITY = {"Account": "account", "Campaign": "campaign", "AdGroup": "ad_group"} - - -def _extension_target(config, account, customer, campaign_id: str, scope: str, - ad_group_id: str = "") -> tuple[str, str, str] | dict: - """(AssociationType, entity id, label) of where an extension links; ad groups only when the caller allows them.""" - if scope == "account": - if campaign_id or ad_group_id: - given = "ad_group_id" if ad_group_id else "campaign_id" - return _validation_error([f"Pass {given} or scope='account', not both."]) - return "Account", account, f"account {account}" - if ad_group_id: - if campaign_id: - return _validation_error(["Pass campaign_id or ad_group_id, not both."]) - found = find_entity(config, account, customer, "ad_group", str(ad_group_id)) - if not found: - return {"error": f"Microsoft ad group '{ad_group_id}' was not found in account {account}."} - return ("AdGroup", str(ad_group_id), - f"ad group '{found['entity'].get('Name')}' in campaign '{found['campaign'].get('Name')}'") - if not campaign_id: - return _validation_error(["campaign_id is required (or scope='account' for every campaign without its own)."]) - found = find_entity(config, account, customer, "campaign", str(campaign_id)) - if not found: - return {"error": f"Microsoft campaign '{campaign_id}' was not found in account {account}."} - return "Campaign", str(campaign_id), f"campaign '{found['entity'].get('Name')}'" - - -def _associated_extensions(config, account, customer, association_type: str, entity_id: str | list[str]) -> list[dict]: - """Extension links of one entity or of up to 100 (Microsoft's EntityIds limit); each carries its EntityId.""" - ids = [str(i) for i in (entity_id if isinstance(entity_id, list) else [entity_id])] - body = {"AccountId": account, "AdExtensionType": _EXTENSION_TYPES, "AssociationType": association_type, - "EntityIds": [int(i) for i in ids]} - payload = campaign_request(config, "AdExtensionsAssociations/Query", body, account_id=account, customer_id=customer) - out = [] - # One collection per requested entity, in the request's order. - for owner, collection in zip(ids, payload.get("AdExtensionAssociationCollection") or [], strict=False): - for assoc in (collection or {}).get("AdExtensionAssociations") or []: - if isinstance(assoc, dict) and isinstance(assoc.get("AdExtension"), dict): - out.append({**assoc, "EntityId": str(assoc.get("EntityId") or owner)}) - return out - - -def _draft_extensions(config, *, ad_account_id, campaign_id, scope, operation, kind, extensions, shown, warnings) -> dict: - blocked = _guard(operation, config) - if blocked: - return blocked - meta, account, customer = _ctx(config, ad_account_id) - target = _extension_target(config, account, customer, str(campaign_id or ""), (scope or "").strip().lower()) - if isinstance(target, dict): - return target - association, entity_id, where = target - existing = _associated_extensions(config, account, customer, association, entity_id) - same = [a["AdExtension"] for a in existing if a["AdExtension"].get("Type") == kind] - if kind == "CallAdExtension" and same: - return _validation_error([f"{where} already has a call extension; Microsoft allows one per campaign."]) - def key(ext): # noqa: E306 - return json.dumps({k: ext.get(k) for k in ("Text", "DisplayText", "Header", "Values", "PhoneNumber")}, sort_keys=True).lower() - have = {key(e) for e in same} - new = [e for e in extensions if key(e) not in have] - if not new: - return {"error": f"Every one of these is already on {where}."} - if len(new) < len(extensions): - warnings.append(f"Skipped {len(extensions) - len(new)} already on {where}.") - return _plan( - operation, _ASSOCIATION_ENTITY[association], entity_id, account, customer, - {"entity_name": where, **shown}, - {"association_type": association, "entity_id": entity_id, "extensions": new}, - warnings=warnings, - ) - - -def draft_microsoft_sitelinks(config, *, ad_account_id="", campaign_id="", scope="", sitelinks=None) -> dict: - errors: list[str] = [] - warnings: list[str] = [] - exts = [] - for i, s in enumerate(sitelinks or []): - if not isinstance(s, dict): - errors.append(f"sitelinks[{i}] must be {{link_text, final_url, description1, description2}}.") - continue - text = str(s.get("link_text") or "").strip() - d1, d2 = str(s.get("description1") or "").strip(), str(s.get("description2") or "").strip() - limit = 25 if (d1 or d2) else 35 - if not text or len(text) > limit: - errors.append(f"sitelinks[{i}].link_text is 1–{limit} characters.") - if bool(d1) != bool(d2): - errors.append(f"sitelinks[{i}] needs both descriptions or neither.") - if len(d1) > 35 or len(d2) > 35: - errors.append(f"sitelinks[{i}] descriptions are at most 35 characters each.") - _check_url(str(s.get("final_url") or "").strip(), errors, warnings, field=f"sitelinks[{i}].final_url") - ext = {"Type": "SitelinkAdExtension", "DisplayText": text, "FinalUrls": [str(s.get("final_url") or "").strip()]} - if d1: - ext.update(Description1=d1, Description2=d2) - exts.append(ext) - if not exts and not errors: - errors.append("sitelinks needs at least one sitelink.") - if len(exts) > 20: - errors.append("At most 20 sitelinks per campaign.") - if errors: - return _validation_error(errors) - if len(exts) < 4: - warnings.append("Four or more sitelinks let Microsoft show the larger sitelink formats.") - return _draft_extensions(config, ad_account_id=ad_account_id, campaign_id=campaign_id, scope=scope, - operation="microsoft_add_sitelinks", kind="SitelinkAdExtension", extensions=exts, - shown={"sitelinks": [ - f"{e['DisplayText']} → {e['FinalUrls'][0]}" - + (f" ({e['Description1']} / {e['Description2']})" if e.get("Description1") else "") - for e in exts]}, - warnings=warnings) - - -def draft_microsoft_callouts(config, *, ad_account_id="", campaign_id="", scope="", callouts=None) -> dict: - errors: list[str] = [] - texts = _clean(callouts) - for t in texts: - if len(t) > 25: - errors.append(f"Callout '{t}' is longer than 25 characters.") - if not texts: - errors.append("callouts needs at least one callout.") - if errors: - return _validation_error(errors) - warnings = [] if len(texts) >= 2 else ["A campaign needs at least 2 callouts before Microsoft shows them."] - exts = [{"Type": "CalloutAdExtension", "Text": t} for t in dict.fromkeys(texts)] - return _draft_extensions(config, ad_account_id=ad_account_id, campaign_id=campaign_id, scope=scope, - operation="microsoft_add_callouts", kind="CalloutAdExtension", extensions=exts, - shown={"callouts": [e["Text"] for e in exts]}, warnings=warnings) - - -def draft_microsoft_structured_snippet(config, *, ad_account_id="", campaign_id="", scope="", header="", values=None) -> dict: - errors: list[str] = [] - vals = list(dict.fromkeys(_clean(values))) - if not (header or "").strip(): - errors.append("header is required (one of Microsoft's headers, e.g. Services, Brands, Types).") - if not 3 <= len(vals) <= 10: - errors.append(f"A structured snippet takes 3–10 values (got {len(vals)}).") - for v in vals: - if len(v) > 25: - errors.append(f"Value '{v}' is longer than 25 characters.") - if errors: - return _validation_error(errors) - ext = {"Type": "StructuredSnippetAdExtension", "Header": header.strip(), "Values": vals} - return _draft_extensions(config, ad_account_id=ad_account_id, campaign_id=campaign_id, scope=scope, - operation="microsoft_add_structured_snippet", kind="StructuredSnippetAdExtension", - extensions=[ext], shown={"snippet": f"{ext['Header']}: {', '.join(vals)}"}, warnings=[]) - - -def draft_microsoft_call_extension(config, *, ad_account_id="", campaign_id="", phone_number="", country_code="") -> dict: - errors: list[str] = [] - number = (phone_number or "").strip() - country = (country_code or "").strip().upper() - if not number or len(number) > 35: - errors.append("phone_number is required (at most 35 characters).") - if len(country) != 2 or not country.isalpha(): - errors.append("country_code is the two-letter country of the number, e.g. US.") - if errors: - return _validation_error(errors) - ext = {"Type": "CallAdExtension", "PhoneNumber": number, "CountryCode": country, "IsCallOnly": False} - return _draft_extensions(config, ad_account_id=ad_account_id, campaign_id=campaign_id, scope="", - operation="microsoft_add_call_extension", kind="CallAdExtension", extensions=[ext], - shown={"phone_number": number, "country_code": country}, - warnings=["Use the call-tracking number that should receive Microsoft calls."]) - - -# --------------------------------------------------------------------------- -# Image extensions -# --------------------------------------------------------------------------- -# Microsoft's limits, from its documentation (checked 2026-11-05): -# [EXT] ImageAdExtension: learn.microsoft.com/advertising/campaign-management-service/imageadextension -# [IMG] Image (media): learn.microsoft.com/advertising/campaign-management-service/image -# [ADD] AddMedia: learn.microsoft.com/advertising/campaign-management-service/addmedia -# [RSA] ResponsiveAd Remarks (same media library): -# learn.microsoft.com/advertising/campaign-management-service/responsivead#remarks -# [BULK] Image Ad Extension record: learn.microsoft.com/advertising/bulk-service/image-ad-extension -# [HELP] Add images to your ad with image extensions: -# learn.microsoft.com/advertising/msa-help/hlp_ba_proc_addimageextension -# [GUIDE] Image guidelines and policies: learn.microsoft.com/advertising/msa-help/hlp_ba_conc_imageguidelines -# [AUD] Audience ads guide: learn.microsoft.com/advertising/guides/audience-ads - -# GIF, JPEG and PNG, no animation [IMG Remarks, GUIDE]. -_IMAGE_FORMATS = {"image/jpeg": "JPEG", "image/png": "PNG", "image/gif": "GIF"} -# "1.91:1 aspect ratio is required for the extension to be eligible to serve" -# with a minimum of 703 x 368 pixels [GUIDE, HELP]; Microsoft crops the other -# placements' ratios from it. The extension links the image as its -# LandscapeImageMedia asset, which is 1.91:1 [BULK images.subType]. -_IMAGE_RATIO = 1.91 -_IMAGE_RATIO_TOLERANCE = 0.01 # 1200x628 is 1.911, 703x368 is 1.910 -_IMAGE_MIN_SIZE = (703, 368) -# "The maximum width and height in pixels are 2592 and 2048 independently" [IMG, RSA]. -_IMAGE_MAX_SIZE = (2592, 2048) -# "The maximum file size is 5 MB" [RSA Remarks]. [IMG] also names a cap of -# 102,400 base64 characters (about 75 KB) for Image.Data, but Microsoft does -# not enforce it on upload: JPEGs of 125-300 KB went through on a live -# account. The draft enforces the 5 MB limit only. -_IMAGE_MAX_BYTES = 5 * 1024 * 1024 -# "You can add a maximum of 10 media in a single call" [ADD]. -_IMAGES_PER_DRAFT = 10 -_ALT_TEXT_MAX = 35 # AlternativeText, required [EXT] -_DISPLAY_TEXT_MAX = 35 # DisplayText, required for the SearchMultiple layout [EXT] -_DESCRIPTION_MAX = 100 # Description, internal label, not shown [EXT] -# Image extensions linked to one account, campaign or ad group: 25 in [BULK] -# and [HELP], 6 in [EXT] and the "About ad extensions" association table. -_IMAGE_LINKS_MAX = 25 -_IMAGE_LINKS_LOW = 6 - - -def _gif_frames(data: bytes) -> int: - """Image frames in a GIF (2 is enough to call it animated).""" - def skip_blocks(i: int) -> int: - while data[i]: - i += data[i] + 1 - return i + 1 - - frames = 0 - try: - flags = data[10] - i = 13 + (3 * 2 ** ((flags & 0x07) + 1) if flags & 0x80 else 0) - while i < len(data) and frames < 2: - block = data[i] - if block == 0x2C: # image descriptor - frames += 1 - flags = data[i + 9] - i += 10 + (3 * 2 ** ((flags & 0x07) + 1) if flags & 0x80 else 0) - i = skip_blocks(i + 1) # LZW minimum code size, then the data - elif block == 0x21: # extension - i = skip_blocks(i + 2) - else: - break - except IndexError: - pass - return frames - - -def _is_animated(data: bytes, mime_type: str) -> bool: - if mime_type == "image/gif": - return _gif_frames(data) > 1 - if mime_type == "image/png": - # An APNG declares its animation (acTL) before the first image data. - actl, idat = data.find(b"acTL"), data.find(b"IDAT") - return actl != -1 and (idat == -1 or actl < idat) - return False - - -def _crop_hint(width: int, height: int) -> str: - if width / height > _IMAGE_RATIO: - return f"{round(height * _IMAGE_RATIO)}x{height}" - return f"{width}x{round(width / _IMAGE_RATIO)}" - - -def _image_problems(label: str, data: bytes, mime_type: str, width: int, height: int) -> list[str]: - """Why Microsoft would refuse this image for an image extension (empty when it fits).""" - problems = [] - if mime_type not in _IMAGE_FORMATS: - problems.append(f"{label}: {mime_type} is not accepted; use JPEG, PNG or GIF.") - elif _is_animated(data, mime_type): - problems.append(f"{label}: animated images are not accepted; use a still image.") - if len(data) > _IMAGE_MAX_BYTES: - problems.append(f"{label}: {len(data) / 1024 / 1024:.1f} MB is over Microsoft's 5 MB limit.") - if width < _IMAGE_MIN_SIZE[0] or height < _IMAGE_MIN_SIZE[1]: - problems.append(f"{label}: {width}x{height} is smaller than Microsoft's minimum of 703x368 for image extensions.") - if width > _IMAGE_MAX_SIZE[0] or height > _IMAGE_MAX_SIZE[1]: - problems.append(f"{label}: {width}x{height} is larger than Microsoft's maximum (width 2592, height 2048); " - "scale it down, e.g. to 1200x628.") - ratio = width / height if height else 0 - if abs(ratio - _IMAGE_RATIO) > _IMAGE_RATIO * _IMAGE_RATIO_TOLERANCE: - problems.append(f"{label}: the aspect ratio is {ratio:.2f}:1; image extensions need 1.91:1 (e.g. 1200x628). " - f"Crop it to {_crop_hint(width, height)} first.") - return problems - - -def _image_label(payload: dict) -> str: - return str(payload.get("url") or payload.get("path") or f"upload {payload.get('upload_id')}") - - -def _draft_images(paths: list[str], urls: list[str], uploads: list[str]) -> tuple[list[dict], list[str]]: - """Load, validate and pin (sha256) every image; the bytes stay out of the plan. - - Loading reuses the Google Ads image tools: image_payloads checks the files - and fetches URLs through the private-address-proof fetcher, and - load_image_bytes reads the approved bytes back. - """ - from adloop.ads.write import image_payloads, load_image_bytes - - payloads, errors = image_payloads(paths, urls, uploads) - images, seen = [], set() - for payload in payloads: - label = _image_label(payload) - try: - data, _name = load_image_bytes(payload) - except Exception as exc: # noqa: BLE001 - a fetch or upload problem is the user's to fix - errors.append(f"{label}: {exc}") - continue - digest = hashlib.sha256(data).hexdigest() - if payload.get("sha256") and payload["sha256"] != digest: - errors.append(f"{label}: the image changed while it was being read; try again.") - continue - if digest in seen: - errors.append(f"{label}: the same image is in this draft twice.") - continue - seen.add(digest) - width, height = int(payload["width"]), int(payload["height"]) - errors.extend(_image_problems(label, data, str(payload["mime_type"]), width, height)) - images.append({**payload, "sha256": digest, "size_bytes": len(data), - "base64_chars": 4 * ((len(data) + 2) // 3)}) - return images, errors - - -def _approved_image(payload: dict) -> bytes: - """The previewed bytes of an image, re-read now; refuses one that changed or no longer fits.""" - from adloop.ads.write import load_image_bytes - - label = _image_label(payload) - data, _name = load_image_bytes(payload) - if hashlib.sha256(data).hexdigest() != payload["sha256"]: - raise ValueError(f"{label} changed since the preview; draft again.") - problems = _image_problems(label, data, str(payload["mime_type"]), int(payload["width"]), int(payload["height"])) - if problems: - raise ValueError("; ".join(problems)) - return data - - -def _describe_ms_image(payload: dict) -> str: - width, height = int(payload["width"]), int(payload["height"]) - return (f"{_image_label(payload)}: {_IMAGE_FORMATS.get(str(payload['mime_type']), payload['mime_type'])} " - f"{width}x{height} ({width / height:.2f}:1), {payload['size_bytes'] / 1024:.1f} KB") - - -def _linked_images(config, account, customer, association: str, entity_id: str) -> list[dict]: - return [a["AdExtension"] for a in _associated_extensions(config, account, customer, association, entity_id) - if a["AdExtension"].get("Type") == "ImageAdExtension"] - - -def draft_microsoft_image_extension( - config: AdLoopConfig, - *, - ad_account_id: str = "", - campaign_id: str = "", - ad_group_id: str = "", - scope: str = "", - image_paths: list[str] | None = None, - image_urls: list[str] | None = None, - upload_ids: list[str] | None = None, - alt_text: str = "", - display_text: str = "", - final_url: str = "", -) -> dict: - """Draft image extensions (one per image) for a campaign, an ad group or the account. - - Every image is loaded and checked now against Microsoft's limits; the - plan keeps its sha256, and the dry run and the apply read it again and - refuse one that changed. The apply uploads the images to the account's - media library (Media/Add), creates one ImageAdExtension per image and - links them (AdExtensionsAssociations/Set). - """ - from adloop.runtime import deployment_mode - - operation = "microsoft_add_image_extension" - blocked = _guard(operation, config) - if blocked: - return blocked - paths, urls, uploads = _clean(image_paths), _clean(image_urls), _clean(upload_ids) - if paths and deployment_mode() == "server": - return {"error": "image_paths can't be used here: local file paths aren't available on a hosted server; " - "pass image_urls or upload_ids instead."} - alt, display, url = (alt_text or "").strip(), (display_text or "").strip(), (final_url or "").strip() - errors: list[str] = [] - warnings: list[str] = [] - if not alt: - errors.append("alt_text is required: it describes the image for screen readers and shows on hover " - f"(at most {_ALT_TEXT_MAX} characters).") - elif len(alt) > _ALT_TEXT_MAX: - errors.append(f"alt_text is {len(alt)} characters; Microsoft allows {_ALT_TEXT_MAX}.") - if len(display) > _DISPLAY_TEXT_MAX: - errors.append(f"display_text is {len(display)} characters; Microsoft allows {_DISPLAY_TEXT_MAX}.") - count = len(paths) + len(urls) + len(uploads) - if not count: - errors.append("At least one image (image_paths, image_urls or upload_ids) is required.") - elif count > _IMAGES_PER_DRAFT: - errors.append(f"At most {_IMAGES_PER_DRAFT} images per draft (Microsoft uploads 10 per request); got {count}.") - if url: - _check_url(url, errors, warnings) - if errors: - return _validation_error(errors) - images, image_errors = _draft_images(paths, urls, uploads) - if image_errors: - return _validation_error(image_errors) - - _meta, account, customer = _ctx(config, ad_account_id) - target = _extension_target(config, account, customer, str(campaign_id or ""), (scope or "").strip().lower(), - ad_group_id=str(ad_group_id or "").strip()) - if isinstance(target, dict): - return target - association, entity_id, where = target - existing = _linked_images(config, account, customer, association, entity_id) - total = len(existing) + len(images) - if total > _IMAGE_LINKS_MAX: - return _validation_error([( - f"{where} has {len(existing)} image extension(s); {len(images)} more would make {total}, over " - f"Microsoft's {_IMAGE_LINKS_MAX} per account, campaign or ad group. Unlink some first " - "(remove_microsoft_entity, entity_type extension_association).")]) - if total > _IMAGE_LINKS_LOW: - warnings.append(f"{where} would have {total} image extensions. Microsoft's image extension reference " - f"lists {_IMAGE_LINKS_LOW} per entity while its help and bulk pages say " - f"{_IMAGE_LINKS_MAX}; if Microsoft refuses the link, the extensions stay in the " - "library unlinked.") - layouts = ["SearchSingle"] + (["SearchMultiple"] if display else []) - # [AUD]: "you can also extend search into native via image ad extensions". - warnings.append("Image extensions can take these search ads beyond Bing results: Microsoft's audience ads " - "guide says search ads are extended to native placements on the Microsoft Audience Network " - "(Outlook, MSN) using their image extensions. Check the ad groups' Audience Network setting " - "(get_microsoft_ad_groups) if they should stay on search.") - if display: - # [HELP]: at least five images and four image extensions; not with - # sitelink, enhanced sitelink, dynamic product, dynamic data or price cards. - warnings.append("display_text makes them eligible for the multi-image layout too. Microsoft shows that " - "layout only with at least five images across at least four image extensions, and not " - "next to sitelink, price, dynamic product or dynamic data extension cards.") - if any(p["mime_type"] == "image/png" for p in images): - warnings.append("Microsoft converts PNG images to JPEG; upload a JPEG if the quality matters.") - if existing: - warnings.append(f"{where} already has {len(existing)} image extension(s); Microsoft rotates them.") - shown: dict[str, Any] = {"images": [_describe_ms_image(p) for p in images], "alt_text": alt} - if display: - shown["display_text"] = display - shown["final_url"] = url or "the ad's own final URL" - shown["layouts"] = layouts - return _plan( - operation, _ASSOCIATION_ENTITY[association], entity_id, account, customer, - {"entity_name": where, **shown}, - {"association_type": association, "entity_id": entity_id, "image_payloads": images}, - warnings=warnings, - ) - - -def _image_extension(c: dict, media_id: str, payload: dict) -> dict: - """The ImageAdExtension for one uploaded image [EXT]; the image is its 1.91:1 LandscapeImageMedia asset.""" - ext: dict[str, Any] = { - "Type": "ImageAdExtension", - "AlternativeText": c["alt_text"], - "Description": str(payload.get("name") or "")[:_DESCRIPTION_MAX] or None, - "ImageMediaIds": [int(media_id)], - "Images": [{"Asset": {"Type": "ImageAsset", "Id": int(media_id), "SubType": "LandscapeImageMedia"}}], - "Layouts": list(c["layouts"]), - } - if c.get("display_text"): - ext["DisplayText"] = c["display_text"] - if c["final_url"].startswith(("http://", "https://")): - ext["FinalUrls"] = [c["final_url"]] - return {k: v for k, v in ext.items() if v is not None} - - -def _extension_row(assoc: dict, association: str, label: str, campaign_name: str | None) -> dict: - ext = assoc["AdExtension"] - kind = str(ext.get("Type") or "") - entity_id = str(assoc["EntityId"]) - row: dict[str, Any] = { - "level": _ASSOCIATION_ENTITY.get(association, association.lower()), "entity": label, "entity_id": entity_id, - "type": kind.replace("AdExtension", ""), "extension_id": str(ext.get("Id")), - "content": ext.get("Text") or ext.get("DisplayText") or ext.get("PhoneNumber") - or (f"{ext.get('Header')}: {', '.join(ext.get('Values') or [])}" if ext.get("Header") else None), - "final_urls": ext.get("FinalUrls"), - "editorial_status": assoc.get("EditorialStatus"), - "remove_id": f"{ext.get('Id')}~{entity_id}~{association}", - } - if association == "AdGroup": - row["campaign"] = campaign_name - if kind == "ImageAdExtension": - row.update(content=ext.get("AlternativeText"), alt_text=ext.get("AlternativeText"), - display_text=ext.get("DisplayText"), media_ids=_image_media_ids(ext), layouts=ext.get("Layouts"), - label=ext.get("Description"), source=ext.get("SourceType")) - return row - - -def _image_media_ids(ext: dict) -> list[str]: - """The media an image extension shows: its ImageMediaIds, or the assets of its Images links.""" - media = [str(i) for i in ext.get("ImageMediaIds") or [] if i is not None] or [ - str(link["Asset"]["Id"]) for link in ext.get("Images") or [] - if isinstance(link, dict) and isinstance(link.get("Asset"), dict) and link["Asset"].get("Id") is not None] - return sorted(set(media), key=lambda m: (len(m), m)) - - -# The association query returns image extensions without their Images, -# DisplayText and Layouts; those come only from GetAdExtensionsByIds when -# ReturnAdditionalFields asks for them (an unknown field name fails the whole -# request). Media metadata then gives each image's size and a viewable URL. -_IMAGE_EXTRA_FIELDS = "Images,DisplayText,Layouts" - - -def _image_details(config: AdLoopConfig, account: str, customer: str, rows: list[dict]) -> list[str]: - """Fill image rows with their media, display text, layouts and image links; insights on failure.""" - image_rows = [r for r in rows if r["type"] == "Image"] - if not image_rows: - return [] - try: - extensions: dict[str, dict] = {} - for chunk in _chunks(sorted({r["extension_id"] for r in image_rows})): - payload = campaign_request( - config, "AdExtensions/QueryByIds", - {"AccountId": account, "AdExtensionIds": [int(i) for i in chunk], - "AdExtensionType": "ImageAdExtension", "ReturnAdditionalFields": _IMAGE_EXTRA_FIELDS}, - account_id=account, customer_id=customer, - ) - extensions.update({str(e.get("Id")): e for e in payload.get("AdExtensions") or [] if isinstance(e, dict)}) - for row in image_rows: - ext = extensions.get(row["extension_id"]) - if ext: - row.update(media_ids=_image_media_ids(ext) or row["media_ids"], - display_text=ext.get("DisplayText") or row["display_text"], - layouts=ext.get("Layouts") or row["layouts"]) - media: dict[str, dict] = {} - for chunk in _chunks(sorted({m for r in image_rows for m in r["media_ids"]})): - payload = campaign_request(config, "MediaMetaData/QueryByIds", - {"AccountId": account, "MediaIds": [int(m) for m in chunk]}, - account_id=account, customer_id=customer) - for item in payload.get("MediaMetaData") or []: - if not isinstance(item, dict): - continue - reps = [r for r in item.get("Representations") or [] if isinstance(r, dict)] - best = max(reps, key=lambda r: (r.get("Width") or 0) * (r.get("Height") or 0), default={}) - media[str(item.get("Id"))] = {"media_id": str(item.get("Id")), "media_type": item.get("MediaType"), - "width": best.get("Width"), "height": best.get("Height"), - "url": best.get("Url")} - except MicrosoftAdsApiError as exc: - return [f"Image details could not be read, so image rows lack their images and display text: {exc}"] - for row in image_rows: - row["images"] = [media.get(m) or {"media_id": m} for m in row["media_ids"]] - return [] - - -def get_microsoft_ad_extensions(config: AdLoopConfig, *, ad_account_id: str = "", campaign_id: str = "") -> dict: - """Sitelinks, callouts, snippets, call and image extensions on ad groups, campaigns and the account.""" - meta, account, customer = _ctx(config, ad_account_id) - campaigns = [c for c in _campaigns(config, account, customer) if not campaign_id or str(c.get("Id")) == str(campaign_id)] - rows = [] - targets = [("Campaign", str(c.get("Id")), c.get("Name")) for c in campaigns] - if not campaign_id: - targets.append(("Account", account, "account")) - for association, entity_id, label in targets: - for a in _associated_extensions(config, account, customer, association, entity_id): - rows.append(_extension_row(a, association, label, None)) - # Ad group links (image extensions often live there), up to 100 ad groups a request. - groups = {str(g.get("Id")): (g, c) for c in campaigns for g in _ad_groups(config, account, customer, str(c.get("Id"))) - if g.get("Status") != "Deleted"} - for chunk in _chunks(list(groups)): - for a in _associated_extensions(config, account, customer, "AdGroup", chunk): - group, campaign = groups.get(a["EntityId"], ({}, {})) - rows.append(_extension_row(a, "AdGroup", group.get("Name") or a["EntityId"], campaign.get("Name"))) - insights = _image_details(config, account, customer, rows) - for c in campaigns: - mine = [r for r in rows if r["level"] == "campaign" and r["entity_id"] == str(c.get("Id"))] - if not any(r["type"] == "Sitelink" for r in mine): - insights.append(f"Campaign '{c.get('Name')}' has no sitelinks of its own.") - rejected = [r for r in rows if r["editorial_status"] in ("Disapproved", "Inactive")] - if rejected: - insights.append(f"{len(rejected)} extension(s) are disapproved or inactive.") - if not any(r["type"] == "Image" for r in rows): - insights.append("No image extensions are linked. Microsoft may add autogenerated ones to ad groups " - "without any; draft_microsoft_image_extension adds your own.") - return {"ad_account_id": account, "extensions": rows, "total": len(rows), "insights": insights} - - -# --------------------------------------------------------------------------- -# Removal -# --------------------------------------------------------------------------- - -REMOVABLE = ("campaign", "ad_group", "ad", "keyword", "negative_keyword", "negative_list_item", - "campaign_criterion", "extension_association") - - -# Criterion types a campaign_criterion remove_id can point at, looked up in -# this order (one query each, until the criterion is found). -_CRITERION_KINDS = ("Location", "Radius", "DayTime", "LocationIntent", "Age", "Gender", "Device") - - -def _find_criterion(by_kind: dict[str, list[dict]], criterion_id: str) -> dict | None: - """The criterion with this id among a campaign's target criteria, with the others of its kind.""" - for kind, rows in by_kind.items(): - for row in rows: - if str(row.get("Id")) == str(criterion_id): - return {"criterion": row, "kind": kind, "siblings": rows} - return None - - -def _criterion_label(row: dict, kind: str) -> str: - crit = row.get("Criterion") or {} - side = "excluded" if is_negative(row) else "targeted" - if kind == "Location": - return f"location {crit.get('DisplayName') or crit.get('LocationId')} ({side})" - if kind == "Radius": - return f"radius {crit.get('Name') or ''} {crit.get('Radius')} {crit.get('RadiusUnit') or ''} ({side})".replace(" ", " ") - if kind == "DayTime": - return f"ad schedule window {_block_label(crit)}" - if kind == "LocationIntent": - return f"location intent {crit.get('IntentOption')}" - return f"{kind.lower()} criterion {row.get('Id')}" - - -def _positive_locations(rows: list[dict]) -> list[dict]: - return [r for r in rows if not is_negative(r)] - - -def _criterion_refusal(campaign_name: str, found: dict, by_kind: dict[str, list[dict]]) -> str | None: - """Why removing this criterion must go through update_microsoft_campaign_targeting, or None.""" - if found["kind"] not in ("Location", "Radius") or is_negative(found["criterion"]): - return None - positives = _positive_locations(by_kind.get("Location", []) + by_kind.get("Radius", [])) - others = [r for r in positives if str(r.get("Id")) != str(found["criterion"].get("Id"))] - if others: - return None - return (f"This is the last targeted location of campaign '{campaign_name}': without it the campaign " - "serves everywhere. Use update_microsoft_campaign_targeting with the full location list instead.") - - -def remove_microsoft_entity(config: AdLoopConfig, *, ad_account_id: str = "", entity_type: str = "", entity_id: str = "") -> dict: - """Draft deleting an entity (irreversible; double confirmation).""" - operation = "microsoft_remove_entity" - blocked = _guard(operation, config) - if blocked: - return blocked - entity_type = (entity_type or "").strip().lower() - entity_id = str(entity_id or "").strip() - if entity_type not in REMOVABLE: - return _validation_error([f"entity_type must be one of {list(REMOVABLE)}."]) - if not entity_id: - return _validation_error(["entity_id is required."]) - meta, account, customer = _ctx(config, ad_account_id) - shown: dict[str, Any] = {} - payload: dict[str, Any] = {} - request: dict[str, Any] - warnings: list[str] = [] - if entity_type in ("campaign", "ad_group", "ad", "keyword"): - found = find_entity(config, account, customer, entity_type, entity_id) - if not found: - return {"error": f"Microsoft {entity_type.replace('_', ' ')} '{entity_id}' was not found."} - entity = found["entity"] - label = entity.get("Name") or entity.get("Text") or f"{entity.get('Type')} ad {entity_id}" - shown = {"name": label, "campaign_name": found["campaign"].get("Name") if entity_type != "campaign" else None, - "ad_group_name": (found.get("ad_group") or {}).get("Name") if entity_type in ("ad", "keyword") else None, - "current_status": entity.get("Status")} - payload = {"campaign_id": str(found["campaign"].get("Id")), - "ad_group_id": str((found.get("ad_group") or {}).get("Id") or "")} - if entity_type == "campaign": - request = {"path": "Campaigns", "body": {"AccountId": account, "CampaignIds": [entity_id]}} - elif entity_type == "ad_group": - request = {"path": "AdGroups", "body": {"CampaignId": str(found["campaign"].get("Id")), "AdGroupIds": [entity_id]}} - elif entity_type == "ad": - request = {"path": "Ads", "body": {"AdGroupId": str(found["ad_group"].get("Id")), "AdIds": [entity_id]}} - else: - request = {"path": "Keywords", "body": {"AdGroupId": str(found["ad_group"].get("Id")), "KeywordIds": [entity_id]}} - warnings.append("Deleting cannot be undone; pausing keeps the history and lets it come back.") - else: - parts = entity_id.split("~") - if entity_type == "negative_keyword" and len(parts) == 3 and parts[0] in ("Campaign", "AdGroup"): - kind, owner, neg = parts - request = {"path": "EntityNegativeKeywords", "body": {"EntityNegativeKeywords": [ - {"EntityId": int(owner), "EntityType": kind, "NegativeKeywords": [{"Id": int(neg)}]}]}} - shown = {"negative_keyword_id": neg, "on": f"{kind} {owner}"} - elif entity_type == "negative_list_item" and len(parts) == 2: - list_id, item = parts - request = {"path": "ListItems", "body": {"ListItemIds": [int(item)], "SharedList": {"Type": _LIST_TYPE, "Id": int(list_id)}, - "SharedEntityScope": "Account"}} - shown = {"list_id": list_id, "item_id": item} - elif entity_type == "campaign_criterion" and len(parts) == 2 and all(x.isdigit() for x in parts): - cid, crit = parts - campaign = find_entity(config, account, customer, "campaign", cid) - if not campaign: - return {"error": f"Microsoft campaign '{cid}' was not found in account {account}."} - name = campaign["entity"].get("Name") - by_kind = target_criterions(config, account, customer, cid, _CRITERION_KINDS) - found = _find_criterion(by_kind, crit) - if not found: - return {"error": f"Campaign '{name}' has no target criterion {crit} (get_microsoft_campaigns lists them)."} - refusal = _criterion_refusal(name, found, by_kind) - if refusal: - return _validation_error([refusal]) - label = _criterion_label(found["criterion"], found["kind"]) - shown = {"name": label, "campaign_name": name, "criterion_type": found["kind"]} - payload = {"campaign_id": cid, "criterion_kind": found["kind"]} - request = {"path": "CampaignCriterions", "body": {"CampaignCriterionIds": [int(crit)], "CampaignId": int(cid), - "CriterionType": "Targets"}} - if found["kind"] == "LocationIntent": - warnings.append("Without its location intent the campaign falls back to Microsoft's default, " - "which also reaches people outside the locations who search for them.") - if found["kind"] == "DayTime" and len(found["siblings"]) == 1: - warnings.append("This is the campaign's last ad schedule window: without it the campaign serves at all hours.") - elif entity_type == "extension_association" and len(parts) == 3 and parts[2] in _ASSOCIATION_ENTITY: - ext, owner, association = parts - request = {"path": "AdExtensionsAssociations", "body": {"AccountId": account, "AssociationType": association, - "AdExtensionIdToEntityIdAssociations": [ - {"AdExtensionId": int(ext), "EntityId": int(owner)}]}} - shown = {"extension_id": ext, "removed_from": f"{association} {owner}"} - warnings.append("This unlinks the extension only; the extension (and an image extension's images) " - "stays in the account's library.") - else: - return _validation_error([ - "entity_id format: negative_keyword 'Campaign~~' or 'AdGroup~~', " - "negative_list_item '~', campaign_criterion '~', " - "extension_association '~~' (the remove_id values the read " - "tools return)." - ]) - return _plan(operation, entity_type, entity_id, account, customer, - {"entity_name": shown.pop("name", None) or entity_id, **shown}, - {**payload, "request": request}, warnings=warnings, double=True) - - -# --------------------------------------------------------------------------- -# Dry run and apply -# --------------------------------------------------------------------------- - -OPERATIONS = { - "microsoft_update_campaign", "microsoft_update_targeting", "microsoft_create_campaign", - "microsoft_create_ad_group", "microsoft_update_ad_group", "microsoft_add_keywords", - "microsoft_update_keyword_bids", "microsoft_add_negative_keywords", "microsoft_create_negative_list", - "microsoft_add_to_negative_list", "microsoft_attach_negative_list", "microsoft_detach_negative_list", - "microsoft_create_rsa", "microsoft_update_rsa", "microsoft_add_sitelinks", "microsoft_add_callouts", - "microsoft_add_structured_snippet", "microsoft_add_call_extension", "microsoft_add_image_extension", - "microsoft_remove_entity", -} - - -def _require_unchanged(entity: dict, before: dict, what: str) -> None: - for key, value in (before or {}).items(): - if not _same(entity.get(key), value): - raise ValueError(f"The {what}'s {key} changed since the draft; draft again.") - - -def preflight(config: AdLoopConfig, plan: ChangePlan) -> dict: - """Re-read what the plan touches and re-check the gates; sends nothing.""" - from adloop.safety.guards import check_budget_cap - - c = plan.apply_payload() - account, customer = c["ad_account_id"], c.get("customer_id", "") - op = plan.operation - checks: dict[str, Any] = {"ad_account_id": account} - - def entity(kind: str, eid: str) -> dict: - # The plan's stored parents keep this to three reads, not a scan of the account. - parent = c.get("ad_group_id", "") if kind in ("keyword", "ad") else "" - found = find_entity(config, account, customer, kind, eid, parent_id=parent or "", - campaign_id=c.get("campaign_id", "") if kind != "campaign" else "") - if not found: - raise ValueError(f"{kind.replace('_', ' ')} '{eid}' no longer exists.") - return found - - if op == "microsoft_update_campaign": - campaign = entity("campaign", plan.entity_id)["entity"] - _require_unchanged(campaign, c["before"], "campaign") - scheme = c["update"].get("BiddingScheme") - if scheme: - _check_bid((((campaign.get("BiddingScheme") or {}).get("MaxCpc")) or {}).get("Amount"), - (scheme.get("MaxCpc") or {}).get("Amount"), config) - strategy = _strategy_name(scheme) - if strategy not in _CONVERSION_BASED: - broad = _active_broad_keywords(config, account, customer, plan.entity_id) - if broad: - raise ValueError(_broad_refusal(len(broad), strategy).replace("The campaign has", "The campaign now has")) - elif (strategy != _strategy_name(c["before"].get("BiddingScheme")) - and _counted_goals(config, account, customer) == 0): - raise ValueError(_no_goal_refusal(strategy)) - elif op == "microsoft_update_targeting": - campaign = entity("campaign", plan.entity_id)["entity"] - now = _current_targeting(config, account, customer, plan.entity_id) - if "searcher_time_zone" in c["before"]: - now["searcher_time_zone"] = bool(campaign.get("AdScheduleUseSearcherTimeZone")) - if now["searcher_time_zone"] != c["before"]["searcher_time_zone"]: - raise ValueError("The campaign's ad schedule time zone setting (AdScheduleUseSearcherTimeZone) " - "changed since the draft, so the approved hours would mean other times; draft again.") - if not _same(now, c["before"]): - raise ValueError("The campaign's targeting changed since the draft; draft again.") - elif op == "microsoft_create_campaign": - check_budget_cap(float(c["daily_budget"]), config.safety) - if c["entity_name"].lower() in {str(x.get("Name")).lower() for x in _campaigns(config, account, customer)}: - raise ValueError(f"A campaign named '{c['entity_name']}' now exists (an earlier attempt may have created it).") - strategy = _strategy_name(c["campaign"].get("BiddingScheme")) - if strategy in _CONVERSION_BASED: - goals = _counted_goals(config, account, customer) - if goals == 0: - raise ValueError(_no_goal_refusal(strategy)) - checks["conversion_goals"] = goals if goals >= 0 else "unknown" - checks["budget_cap_ok"] = True - elif op == "microsoft_create_ad_group": - campaign = entity("campaign", c["campaign_id"])["entity"] - if c["entity_name"].lower() in {str(g.get("Name")).lower() for g in _ad_groups(config, account, customer, c["campaign_id"])}: - raise ValueError(f"An ad group named '{c['entity_name']}' now exists in the campaign.") - errors = [] - _refuse_broad_without_conversion_bidding(c["keyword_rows"], campaign, errors) - if _strategy_name(campaign.get("BiddingScheme")) in _MANUAL and not c["ad_group"].get("CpcBid"): - errors.append("The campaign now uses manual bidding, which needs a default bid for the ad group.") - if errors: - raise ValueError("; ".join(errors)) - elif op == "microsoft_update_ad_group": - group = entity("ad_group", plan.entity_id)["entity"] - _require_unchanged(group, c["before"], "ad group") - if "CpcBid" in c["update"]: - _check_bid(_money(group.get("CpcBid")), c["update"]["CpcBid"]["Amount"], config) - elif op == "microsoft_add_keywords": - found = entity("ad_group", plan.entity_id) - errors = [] - _refuse_broad_without_conversion_bidding(c["keyword_rows"], found["campaign"], errors) - if errors: - raise ValueError("; ".join(errors)) - have = {(str(k.get("Text")).lower(), k.get("MatchType")) for k in _keywords(config, account, customer, plan.entity_id) - if k.get("Status") != "Deleted"} - again = [r["Text"] for r in c["keyword_rows"] if (r["Text"].lower(), r["MatchType"]) in have] - if again: - raise ValueError(f"Keyword(s) {again} are in the ad group now (an earlier attempt may have added them).") - elif op == "microsoft_update_keyword_bids": - group = entity("ad_group", plan.entity_id)["entity"] - if not _same(group.get("CpcBid"), c.get("default_bid_before")): - raise ValueError("The ad group's default bid changed since the draft; draft again.") - now = {str(k.get("Id")): k.get("Bid") for k in _keywords(config, account, customer, plan.entity_id)} - for kid, bid in (c["before"] or {}).items(): - if kid not in now: - raise ValueError(f"Keyword {kid} no longer exists.") - if not _same(now[kid], bid): - raise ValueError(f"Keyword {kid}'s bid changed since the draft; draft again.") - default = _money(group.get("CpcBid")) - for row in c["keyword_rows"]: - current = _money(now[str(row["Id"])]) or default - proposed = row["Bid"]["Amount"] if row["Bid"]["Amount"] is not None else default - _check_bid(current, proposed, config) - elif op == "microsoft_add_negative_keywords": - found = entity(plan.entity_type, plan.entity_id) - have = {(str(n.get("Text")).lower(), n.get("MatchType")) for n in _entity_negatives( - config, account, customer, c["entity_kind"], plan.entity_id, - "" if plan.entity_type == "campaign" else str(found["campaign"].get("Id")))} - again = [r["Text"] for r in c["negative_rows"] if (r["Text"].lower(), r["MatchType"]) in have] - if again: - raise ValueError(f"Negative(s) {again} are there now (an earlier attempt may have added them).") - elif op == "microsoft_create_negative_list": - if c["entity_name"].lower() in {str(x.get("Name")).lower() for x in _shared_lists(config, account, customer)}: - raise ValueError(f"A list named '{c['entity_name']}' now exists (an earlier attempt may have created it).") - elif op in ("microsoft_add_to_negative_list", "microsoft_attach_negative_list", "microsoft_detach_negative_list"): - if plan.entity_id not in {str(x.get("Id")) for x in _shared_lists(config, account, customer)}: - raise ValueError(f"Negative keyword list {plan.entity_id} no longer exists.") - if op == "microsoft_add_to_negative_list": - have = {(str(i.get("Text")).lower(), i.get("MatchType")) for i in _list_items(config, account, customer, plan.entity_id)} - again = [r["Text"] for r in c["negative_rows"] if (r["Text"].lower(), r["MatchType"]) in have] - if again: - raise ValueError(f"Negative(s) {again} are in the list now (an earlier attempt may have added them).") - elif op == "microsoft_create_rsa": - found = entity("ad_group", plan.entity_id) - errors: list[str] = [] - _check_url(c["final_url"], errors, []) - if errors: - raise ValueError("; ".join(errors)) - wanted = sorted(l["Asset"]["Text"] for l in c["ad"]["Headlines"]) - for ad in _ads(config, account, customer, plan.entity_id): - if sorted(str(l.get("Asset", {}).get("Text")) for l in ad.get("Headlines") or []) == wanted: - raise ValueError(f"Ad group '{found['entity'].get('Name')}' already has an RSA with these headlines (ad {ad.get('Id')}).") - elif op == "microsoft_update_rsa": - found = entity("ad", plan.entity_id) - _require_unchanged(found["entity"], c["before"], "ad") - if c["update"].get("FinalUrls"): - errors = [] - _check_url(c["update"]["FinalUrls"][0], errors, []) - if errors: - raise ValueError("; ".join(errors)) - elif op in ("microsoft_add_sitelinks", "microsoft_add_callouts", "microsoft_add_structured_snippet", - "microsoft_add_call_extension"): - if c["association_type"] == "Campaign": - entity("campaign", c["entity_id"]) - linked = _associated_extensions(config, account, customer, c["association_type"], c["entity_id"]) - if op == "microsoft_add_call_extension" and any(a["AdExtension"].get("Type") == "CallAdExtension" for a in linked): - raise ValueError("The campaign got a call extension since the draft.") - def key(ext): # noqa: E306 - return json.dumps({k: ext.get(k) for k in ("Type", "Text", "DisplayText", "Header", "Values", "PhoneNumber")}, - sort_keys=True).lower() - now = {key(a["AdExtension"]) for a in linked} - again = [e for e in c["extensions"] if key(e) in now] - if again: - raise ValueError(f"{len(again)} of these extensions are linked now (an earlier attempt may have added them).") - if op == "microsoft_add_sitelinks": - errors = [] - for ext in c["extensions"]: - _check_url(ext["FinalUrls"][0], errors, []) - if errors: - raise ValueError("; ".join(errors)) - elif op == "microsoft_add_image_extension": - if c["association_type"] in ("Campaign", "AdGroup"): - entity(_ASSOCIATION_ENTITY[c["association_type"]], c["entity_id"]) - images = c["image_payloads"] - for payload in images: - _approved_image(payload) # re-reads (URLs re-fetched) and re-checks every image - linked = _linked_images(config, account, customer, c["association_type"], c["entity_id"]) - if len(linked) + len(images) > _IMAGE_LINKS_MAX: - raise ValueError(f"{c['entity_name']} now has {len(linked)} image extension(s); {len(images)} more would " - f"go over Microsoft's {_IMAGE_LINKS_MAX}.") - if c["final_url"].startswith(("http://", "https://")): - errors = [] - _check_url(c["final_url"], errors, []) - if errors: - raise ValueError("; ".join(errors)) - checks["images_verified"] = len(images) - elif op == "microsoft_remove_entity": - if plan.entity_type in ("campaign", "ad_group", "ad", "keyword"): - entity(plan.entity_type, plan.entity_id) - elif plan.entity_type == "campaign_criterion": - cid, crit = plan.entity_id.split("~") - name = entity("campaign", cid)["entity"].get("Name") - by_kind = target_criterions(config, account, customer, cid, _CRITERION_KINDS) - found = _find_criterion(by_kind, crit) - if not found: - raise ValueError(f"Criterion {crit} is no longer on campaign '{name}'.") - refusal = _criterion_refusal(name, found, by_kind) - if refusal: - raise ValueError(refusal) - else: - raise ValueError(f"Unknown Microsoft operation: {op}") - checks["checked"] = op.replace("microsoft_", "") - return checks - - -def apply_plan(config: AdLoopConfig, plan: ChangePlan) -> dict: - """Execute a management plan (after :func:`preflight`, which the caller runs first).""" - c = plan.apply_payload() - account = c["ad_account_id"] - op = plan.operation - progress = _Progress() - - if op == "microsoft_update_campaign": - _call(config, c, "PUT", "Campaigns", {"AccountId": account, "Campaigns": [c["update"]]}, "campaign update") - return {"campaign_id": plan.entity_id, "updated": sorted(k for k in c["update"] if k != "Id")} - - if op == "microsoft_update_targeting": - ops = c["operations"] - for chunk in _chunks(ops["add"]): - progress.step("Adding targeting", lambda chunk=chunk: _call( - config, c, "POST", "CampaignCriterions", {"CampaignCriterions": chunk, "CriterionType": "Targets"}, "targeting additions")) - progress.done.append(f"added {len(chunk)} criterion(s)") - for chunk in _chunks(ops["update"]): - progress.step("Updating location intent", lambda chunk=chunk: _call( - config, c, "PUT", "CampaignCriterions", {"CampaignCriterions": chunk, "CriterionType": "Targets"}, "location intent")) - progress.done.append("updated location intent") - for chunk in _chunks(ops["delete"]): - progress.step("Removing old targeting", lambda chunk=chunk: _call( - config, c, "DELETE", "CampaignCriterions", - {"CampaignCriterionIds": [int(x) for x in chunk], "CampaignId": int(plan.entity_id), "CriterionType": "Targets"}, - "targeting removal")) - progress.done.append(f"removed {len(chunk)} criterion(s)") - # Schedule windows: non-overlapping new ones, then the old ones out, - # then the rest (see _schedule_steps). - for chunk in _chunks(ops.get("schedule_add_first") or []): - progress.step("Adding new ad schedule windows", lambda chunk=chunk: _call( - config, c, "POST", "CampaignCriterions", {"CampaignCriterions": chunk, "CriterionType": "Targets"}, "ad schedule")) - progress.done.append(f"added {len(chunk)} schedule window(s)") - for chunk in _chunks(ops.get("schedule_delete") or []): - progress.step("Removing the old ad schedule windows", lambda chunk=chunk: _call( - config, c, "DELETE", "CampaignCriterions", - {"CampaignCriterionIds": [int(x) for x in chunk], "CampaignId": int(plan.entity_id), "CriterionType": "Targets"}, - "ad schedule removal")) - progress.done.append(f"removed {len(chunk)} schedule window(s)") - remaining = list(ops.get("schedule_kept") or []) - if ops.get("schedule_add_first"): - remaining.append(f"{len(ops['schedule_add_first'])} new window(s) added before the removal") - for chunk in _chunks(ops.get("schedule_add_after") or []): - progress.step( - "Adding the new ad schedule windows (the windows they replace are already removed; until this " - "succeeds the campaign keeps " - + (", ".join(remaining) if remaining else "no ad schedule and serves at all hours") + ")", - lambda chunk=chunk: _call(config, c, "POST", "CampaignCriterions", - {"CampaignCriterions": chunk, "CriterionType": "Targets"}, "ad schedule")) - progress.done.append(f"added {len(chunk)} schedule window(s)") - schedule_added = len(ops.get("schedule_add_first") or []) + len(ops.get("schedule_add_after") or []) - return {"campaign_id": plan.entity_id, "added": len(ops["add"]) + schedule_added, "updated": len(ops["update"]), - "removed": len(ops["delete"]) + len(ops.get("schedule_delete") or [])} - - if op == "microsoft_create_campaign": - payload = _call(config, c, "POST", "Campaigns", {"AccountId": account, "Campaigns": [c["campaign"]]}, "new campaign") - campaign_id = str((payload.get("CampaignIds") or [None])[0]) - progress.done.append(f"created campaign {campaign_id} (paused)") - criteria = [{**x, "CampaignId": campaign_id} for x in c["criteria"]] - for chunk in _chunks(criteria): - progress.step("Adding the campaign's locations", lambda chunk=chunk: _call( - config, c, "POST", "CampaignCriterions", {"CampaignCriterions": chunk, "CriterionType": "Targets"}, "locations")) - return {"campaign_id": campaign_id, "name": c["entity_name"], "status": "Paused", - "next": "Add ad groups, keywords, ads and extensions, then enable it."} - - if op == "microsoft_create_ad_group": - payload = _call(config, c, "POST", "AdGroups", {"CampaignId": c["campaign_id"], "AdGroups": [c["ad_group"]]}, "new ad group") - ad_group_id = str((payload.get("AdGroupIds") or [None])[0]) - progress.done.append(f"created ad group {ad_group_id}") - for chunk in _chunks(c["keyword_rows"], 1000): - progress.step("Adding its keywords", lambda chunk=chunk: _call( - config, c, "POST", "Keywords", {"AdGroupId": ad_group_id, "Keywords": chunk}, "keywords")) - return {"ad_group_id": ad_group_id, "name": c["entity_name"], "keywords_added": len(c["keyword_rows"])} - - if op == "microsoft_update_ad_group": - _call(config, c, "PUT", "AdGroups", {"CampaignId": c["campaign_id"], "AdGroups": [c["update"]], - "UpdateAudienceAdsBidAdjustment": bool(c.get("update_audience_adjustment"))}, - "ad group update") - return {"ad_group_id": plan.entity_id, "updated": sorted(k for k in c["update"] if k != "Id")} - - if op == "microsoft_add_keywords": - payload = _call(config, c, "POST", "Keywords", {"AdGroupId": plan.entity_id, "Keywords": c["keyword_rows"]}, "keywords") - return {"ad_group_id": plan.entity_id, "keyword_ids": [str(i) for i in payload.get("KeywordIds") or []]} - - if op == "microsoft_update_keyword_bids": - _call(config, c, "PUT", "Keywords", {"AdGroupId": plan.entity_id, "Keywords": c["keyword_rows"]}, "keyword bids") - return {"ad_group_id": plan.entity_id, "keywords_updated": len(c["keyword_rows"])} - - if op == "microsoft_add_negative_keywords": - _call(config, c, "POST", "EntityNegativeKeywords", {"EntityNegativeKeywords": [ - {"EntityId": int(plan.entity_id), "EntityType": c["entity_kind"], "NegativeKeywords": c["negative_rows"]}]}, - "negative keywords") - return {"entity": c["entity_name"], "negatives_added": len(c["negative_rows"])} - - if op == "microsoft_create_negative_list": - items = [{"Type": "NegativeKeyword", **r} for r in c["negative_rows"]] - payload = _call(config, c, "POST", "SharedEntity", {"SharedEntity": {"Type": _LIST_TYPE, "Name": c["entity_name"]}, - "ListItems": items[:5000], "SharedEntityScope": "Account"}, - "negative keyword list") - list_id = str(payload.get("SharedEntityId")) - progress.done.append(f"created list {list_id} with {len(items)} negatives") - if c["campaign_ids"]: - progress.step("Attaching the list", lambda: _call(config, c, "POST", "SharedEntityAssociations/Set", { - "Associations": [{"EntityId": int(cid), "EntityType": "Campaign", "SharedEntityId": int(list_id), - "SharedEntityType": _LIST_TYPE} for cid in c["campaign_ids"]], - "SharedEntityScope": "Account"}, "list attachment")) - return {"list_id": list_id, "name": c["entity_name"], "negatives": len(items), "attached_to": c["attach_to"]} - - if op == "microsoft_add_to_negative_list": - items = [{"Type": "NegativeKeyword", **r} for r in c["negative_rows"]] - for chunk in _chunks(items, 5000): - progress.step("Adding to the list", lambda chunk=chunk: _call(config, c, "POST", "ListItems", { - "ListItems": chunk, "SharedList": {"Type": _LIST_TYPE, "Id": int(plan.entity_id)}, - "SharedEntityScope": "Account"}, "list items")) - return {"list_id": plan.entity_id, "negatives_added": len(items)} - - if op in ("microsoft_attach_negative_list", "microsoft_detach_negative_list"): - body = {"Associations": [{"EntityId": int(cid), "EntityType": "Campaign", "SharedEntityId": int(plan.entity_id), - "SharedEntityType": _LIST_TYPE} for cid in c["campaign_ids"]], - "SharedEntityScope": "Account"} - if op == "microsoft_attach_negative_list": - _call(config, c, "POST", "SharedEntityAssociations/Set", body, "list attachment") - else: - _call(config, c, "DELETE", "SharedEntityAssociations", body, "list detachment") - return {"list_id": plan.entity_id, "campaigns": c["campaigns"]} - - if op == "microsoft_create_rsa": - payload = _call(config, c, "POST", "Ads", {"AdGroupId": plan.entity_id, "Ads": [c["ad"]]}, "responsive search ad") - return {"ad_id": str((payload.get("AdIds") or [None])[0]), "status": "Paused", - "next": "Enable it with enable_microsoft_entity once reviewed."} - - if op == "microsoft_update_rsa": - _call(config, c, "PUT", "Ads", {"AdGroupId": c["ad_group_id"], "Ads": [c["update"]]}, "responsive search ad update") - return {"ad_id": plan.entity_id, "updated": sorted(k for k in c["update"] if k not in ("Id", "Type"))} - - if op in ("microsoft_add_sitelinks", "microsoft_add_callouts", "microsoft_add_structured_snippet", - "microsoft_add_call_extension"): - payload = _call(config, c, "POST", "AdExtensions", {"AccountId": account, "AdExtensions": c["extensions"]}, "extensions") - ids = [str((i or {}).get("Id")) for i in payload.get("AdExtensionIdentities") or [] if i] - progress.done.append(f"created extension(s) {ids}") - progress.step("Linking the extensions", lambda: _call(config, c, "POST", "AdExtensionsAssociations/Set", { - "AccountId": account, "AssociationType": c["association_type"], - "AdExtensionIdToEntityIdAssociations": [{"AdExtensionId": int(i), "EntityId": int(c["entity_id"])} for i in ids], - }, "extension links")) - return {"extension_ids": ids, "linked_to": c["entity_name"]} - - if op == "microsoft_add_image_extension": - return _apply_image_extensions(config, c, progress) - - if op == "microsoft_remove_entity": - request = c["request"] - _call(config, c, "DELETE", request["path"], request["body"], f"{plan.entity_type.replace('_', ' ')} removal") - return {"removed": plan.entity_type, "entity_id": plan.entity_id} - - raise ValueError(f"Unknown Microsoft operation: {op}") - - -def _apply_image_extensions(config: AdLoopConfig, c: dict, progress: _Progress) -> dict: - """Media/Add, then one ImageAdExtension per image, then the links; a later failure names what exists.""" - from adloop.safety.outcomes import PartialApplyError - - account = c["ad_account_id"] - payloads = c["image_payloads"] - # Every image is read and checked before anything is sent. - data = [_approved_image(p) for p in payloads] - # REST v13 AddMedia is POST .../CampaignManagement/v13/Media [ADD]; GenericImage - # is the MediaType Microsoft recommends for image extension media [IMG]. - media = [{"Type": "Image", "MediaType": "GenericImage", "Data": base64.b64encode(d).decode("ascii")} for d in data] - payload = _call(config, c, "POST", "Media", {"AccountId": account, "Media": media}, "image upload") - media_ids = [str(i) for i in payload.get("MediaIds") or [] if i is not None] - if len(media_ids) != len(media): - raise PartialApplyError( - f"Microsoft stored {len(media_ids)} of {len(media)} images (media ids {media_ids}) without saying why; " - "check the account's image library before drafting again.", - created={"media_ids": media_ids}, - ) - progress.created["media_ids"] = media_ids - progress.done.append(f"uploaded {len(media_ids)} image(s) to the media library (media ids {', '.join(media_ids)})") - - extensions = [_image_extension(c, mid, p) for mid, p in zip(media_ids, payloads, strict=True)] - payload = progress.step("Creating the image extensions", lambda: _call( - config, c, "POST", "AdExtensions", {"AccountId": account, "AdExtensions": extensions}, "image extensions")) - ids = [str((i or {}).get("Id")) for i in payload.get("AdExtensionIdentities") or [] if i and i.get("Id")] - progress.created["extension_ids"] = ids - progress.done.append(f"created image extension(s) {', '.join(ids)}") - progress.step("Linking the image extensions", lambda: _call(config, c, "POST", "AdExtensionsAssociations/Set", { - "AccountId": account, "AssociationType": c["association_type"], - "AdExtensionIdToEntityIdAssociations": [{"AdExtensionId": int(i), "EntityId": int(c["entity_id"])} for i in ids], - }, "image extension links")) - return {"media_ids": media_ids, "extension_ids": ids, "linked_to": c["entity_name"], "layouts": c["layouts"], - "next": "The images go through Microsoft's editorial review; get_microsoft_ad_extensions shows each " - "extension's editorial_status."} diff --git a/src/adloop/microsoft_ads/manage/__init__.py b/src/adloop/microsoft_ads/manage/__init__.py new file mode 100644 index 00000000..4c91fade --- /dev/null +++ b/src/adloop/microsoft_ads/manage/__init__.py @@ -0,0 +1,178 @@ +"""Microsoft Advertising management: campaigns, targeting, ad groups, keywords, +negatives, responsive search ads, ad extensions (image extensions included) +and removals. + +Every function here drafts a :class:`ChangePlan` (platform ``microsoft``, +operation ``microsoft_*``) and returns its preview; nothing changes until +``confirm_and_apply``. :mod:`adloop.microsoft_ads.write` routes these +operations to :func:`preflight` and :func:`apply_plan` below. + +Microsoft's Campaign Management API has no validate-only mode, so: + +- **Updates** store a snapshot of every field they change; the dry run and + the apply re-read the entity and refuse when one of those fields was + edited in Microsoft Advertising since the preview. +- **Creates** re-check their parents, the safety caps and (for named + objects) that the name is still free, so a retried apply after a partial + failure refuses instead of creating a second copy. +- **Multi-step applies** (a campaign and then its targeting, a list and then + its attachments) report exactly what was created when a later step fails. + +A plan's ``changes`` hold what the person approves (names, before → after); +request bodies, snapshots and ids live in ``ChangePlan.apply_only_payload``, +which no preview, dialog, card or audit entry shows. The dry run and the +apply read both through ``plan.apply_payload()``. + +REST conventions (learn.microsoft.com/advertising/campaign-management-service): +add is POST, update PUT, delete DELETE on the collection path; polymorphic +objects carry a ``Type`` discriminator; on update an omitted field stays as +it is and a list that is sent replaces the old one. + +The code is split by area (campaigns, targeting, ad_groups, negatives, ads, +extensions, removal). Each area module drafts its plans and registers its +operations in ``HANDLERS``: operation -> (dry-run check, apply). The +package merges them into one table, so :func:`preflight` and +:func:`apply_plan` look an operation up instead of walking a chain of +branches. +""" + +from __future__ import annotations + +from typing import TYPE_CHECKING + +from adloop.microsoft_ads.manage import ( + ad_groups, + ads, + campaigns, + extensions, + negatives, + removal, + targeting, +) +from adloop.microsoft_ads.manage._common import ( + MATCH_TYPES, + NEGATIVE_MATCH_TYPES, + STRATEGIES, + Handler, + Step, + _counted_goals, + _Progress, + _raise_partial, + bidding_scheme, +) +from adloop.microsoft_ads.manage.ad_groups import ( + draft_microsoft_ad_group, + draft_microsoft_keywords, + update_microsoft_ad_group, + update_microsoft_keyword_bids, +) +from adloop.microsoft_ads.manage.ads import ( + draft_microsoft_responsive_search_ad, + update_microsoft_responsive_search_ad, +) +from adloop.microsoft_ads.manage.campaigns import ( + draft_microsoft_campaign, + update_microsoft_campaign, +) +from adloop.microsoft_ads.manage.extensions import ( + draft_microsoft_call_extension, + draft_microsoft_callouts, + draft_microsoft_image_extension, + draft_microsoft_sitelinks, + draft_microsoft_structured_snippet, + get_microsoft_ad_extensions, +) +from adloop.microsoft_ads.manage.negatives import ( + add_microsoft_negative_keywords, + add_to_microsoft_negative_keyword_list, + attach_microsoft_negative_keyword_list, + detach_microsoft_negative_keyword_list, + get_microsoft_negative_keywords, + propose_microsoft_negative_keyword_list, +) +from adloop.microsoft_ads.manage.removal import ( + REMOVABLE, + remove_microsoft_entity, +) +from adloop.microsoft_ads.manage.targeting import ( + _block_span, + _current_targeting, + update_microsoft_campaign_targeting, +) + +if TYPE_CHECKING: + from adloop.config import AdLoopConfig + from adloop.safety.preview import ChangePlan + +HANDLERS: dict[str, Handler] = { + **campaigns.HANDLERS, + **targeting.HANDLERS, + **ad_groups.HANDLERS, + **negatives.HANDLERS, + **ads.HANDLERS, + **extensions.HANDLERS, + **removal.HANDLERS, +} +OPERATIONS = frozenset(HANDLERS) + + +def _handler(plan: ChangePlan) -> Handler: + handler = HANDLERS.get(plan.operation) + if handler is None: + raise ValueError(f"Unknown Microsoft operation: {plan.operation}") + return handler + + +def preflight(config: AdLoopConfig, plan: ChangePlan) -> dict: + """Re-read what the plan touches and re-check the gates; sends nothing.""" + step = Step(config, plan) + _handler(plan).preflight(step) + step.checks["checked"] = plan.operation.replace("microsoft_", "") + return step.checks + + +def apply_plan(config: AdLoopConfig, plan: ChangePlan) -> dict: + """Execute a management plan (after :func:`preflight`, which the caller runs first).""" + return _handler(plan).apply(Step(config, plan), _Progress()) + + +__all__ = [ + "HANDLERS", + "Handler", + "MATCH_TYPES", + "NEGATIVE_MATCH_TYPES", + "OPERATIONS", + "REMOVABLE", + "STRATEGIES", + "Step", + "_Progress", + "_block_span", + "_counted_goals", + "_current_targeting", + "_raise_partial", + "add_microsoft_negative_keywords", + "add_to_microsoft_negative_keyword_list", + "apply_plan", + "attach_microsoft_negative_keyword_list", + "bidding_scheme", + "detach_microsoft_negative_keyword_list", + "draft_microsoft_ad_group", + "draft_microsoft_call_extension", + "draft_microsoft_callouts", + "draft_microsoft_campaign", + "draft_microsoft_image_extension", + "draft_microsoft_keywords", + "draft_microsoft_responsive_search_ad", + "draft_microsoft_sitelinks", + "draft_microsoft_structured_snippet", + "get_microsoft_ad_extensions", + "get_microsoft_negative_keywords", + "preflight", + "propose_microsoft_negative_keyword_list", + "remove_microsoft_entity", + "update_microsoft_ad_group", + "update_microsoft_campaign", + "update_microsoft_campaign_targeting", + "update_microsoft_keyword_bids", + "update_microsoft_responsive_search_ad", +] diff --git a/src/adloop/microsoft_ads/manage/_common.py b/src/adloop/microsoft_ads/manage/_common.py new file mode 100644 index 00000000..ed8bbbef --- /dev/null +++ b/src/adloop/microsoft_ads/manage/_common.py @@ -0,0 +1,310 @@ +"""Constants and helpers every Microsoft Advertising management area shares.""" + +from __future__ import annotations + +import json +from collections.abc import Callable +from typing import TYPE_CHECKING, Any, NamedTuple + +from adloop.microsoft_ads.auth import MicrosoftAdsApiError +from adloop.microsoft_ads.client import campaign_request, fault_details +from adloop.microsoft_ads.read import ( + CONVERSION_BASED_STRATEGIES, + _ad_groups, + _conversion_goals, + _customer, + _keywords, + account_meta, +) +from adloop.microsoft_ads.write import ( + find_entity, + store_plan_preview, +) + +if TYPE_CHECKING: + from adloop.config import AdLoopConfig + from adloop.safety.preview import ChangePlan + + +# The strategies a draft can set. +STRATEGIES = ("ManualCpc", "EnhancedCpc", "MaxClicks", "MaxConversions") +# Broad match needs one of these (read.CONVERSION_BASED_STRATEGIES); Maximize +# Clicks is automated but not conversion-based, so it does not count. +_CONVERSION_BASED = CONVERSION_BASED_STRATEGIES +_MANUAL = {"ManualCpc", "EnhancedCpc"} +# Strategies that take a maximum CPC cap. +_CAPPED = {"MaxClicks", "MaxConversions"} +_ALTERNATIVES = "MaxClicks, EnhancedCpc or ManualCpc" +MATCH_TYPES = ("Exact", "Phrase", "Broad") +NEGATIVE_MATCH_TYPES = ("Exact", "Phrase") +NETWORKS = ("OwnedAndOperatedOnly", "OwnedAndOperatedAndSyndicatedSearch") +INTENTS = ("PeopleIn", "PeopleInOrSearchingForOrViewingPages") +DAYS = ("Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday") +_MINUTES = {0: "Zero", 15: "Fifteen", 30: "Thirty", 45: "FortyFive"} +_PINS = { + "headline_1": "Headline1", "headline_2": "Headline2", "headline_3": "Headline3", + "headline1": "Headline1", "headline2": "Headline2", "headline3": "Headline3", + "description_1": "Description1", "description_2": "Description2", + "description1": "Description1", "description2": "Description2", +} +_EXTENSION_TYPES = ("SitelinkAdExtension, CalloutAdExtension, StructuredSnippetAdExtension, CallAdExtension, " + "ImageAdExtension") +_LIST_TYPE = "NegativeKeywordList" +_MAX_LISTS_PER_CAMPAIGN = 20 +_CHUNK = 100 + + +# --------------------------------------------------------------------------- +# Shared helpers +# --------------------------------------------------------------------------- + + +def _ctx(config: AdLoopConfig, ad_account_id: str) -> tuple[dict, str, str]: + meta = account_meta(config, ad_account_id) + return meta, meta["ad_account_id"], _customer(config, meta) + + +def _clean(values: Any) -> list[str]: + if values is None: + return [] + if isinstance(values, (str, int)): + values = [values] + return [str(v).strip() for v in values if str(v).strip()] + + +def _same(a: Any, b: Any) -> bool: + return json.dumps(a, sort_keys=True, default=str) == json.dumps(b, sort_keys=True, default=str) + + +def _check_url(url: str, errors: list[str], warnings: list[str], field: str = "final_url") -> None: + if not url.startswith(("http://", "https://")): + errors.append(f"{field} must start with http:// or https://") + return + from adloop.ads.write import _validate_urls + + bad, inconclusive = _validate_urls([url]) + if bad.get(url): + errors.append(f"{field} '{url}' is not reachable: {bad[url]}") + warnings.extend(inconclusive.values()) + + +_ID_FIELDS = ("CampaignIds", "AdGroupIds", "KeywordIds", "AdIds", "CampaignCriterionIds", "ListItemIds", "MediaIds") + + +def _created_ids(payload: dict) -> list[str]: + """IDs a create reported as done (failed items come back as null).""" + ids: list[str] = [] + for field in _ID_FIELDS: + ids += [str(i) for i in payload.get(field) or [] if i is not None] + ids += [str((i or {}).get("Id")) for i in payload.get("AdExtensionIdentities") or [] if i and i.get("Id")] + if payload.get("SharedEntityId"): + ids.append(str(payload["SharedEntityId"])) + for group in payload.get("NegativeKeywordIds") or []: + ids += [str(i) for i in (group or {}).get("Ids") or [] if i is not None] + return ids + + +def _partial_errors(payload: dict) -> list[dict]: + entries = [e for e in payload.get("PartialErrors") or [] if e] + for nested in payload.get("NestedPartialErrors") or []: + if not isinstance(nested, dict): + continue + entries.extend(e for e in nested.get("BatchErrors") or [] if e) + if nested.get("ErrorCode") or nested.get("Message"): + entries.append(nested) + return entries + + +def _raise_partial(payload: dict, what: str) -> None: + entries = _partial_errors(payload) + if not entries: + return + _codes, message, _tracking = fault_details({"PartialErrors": entries}) + created = _created_ids(payload) + if created: + # Some items were created and some refused: replaying the plan would + # create the successful ones again. + from adloop.safety.outcomes import PartialApplyError + + raise PartialApplyError( + f"Microsoft created part of the {what} (ids {created}) and refused the rest: {message or entries}", + created={what: created}, + ) + raise MicrosoftAdsApiError(f"Microsoft refused the {what}: {message or entries}") + + +def _call(config: AdLoopConfig, changes: dict, method: str, path: str, body: dict, what: str) -> dict: + try: + payload = campaign_request( + config, path, body, account_id=changes["ad_account_id"], customer_id=changes.get("customer_id", ""), + method=method, mutation=True, + ) + except MicrosoftAdsApiError as exc: + if method == "POST" and (exc.status == 0 or exc.status >= 500): + # The request may have reached Microsoft and created something: + # these creates have no idempotency, so replaying the plan could + # create it twice. Retire the plan and say so. + from adloop.safety.outcomes import PartialApplyError + + raise PartialApplyError( + f"Microsoft did not confirm the {what} ({exc}); it may or may not have been created. " + "Check the account before drafting it again.", + unknown=True, + ) from None + raise + _raise_partial(payload, what) + return payload + + +class _Progress: + """What a multi-step apply already changed, for an honest error. + + Once one step has changed the account, a failure in a later step retires + the plan (PartialApplyError) instead of leaving it to be replayed. + """ + + def __init__(self) -> None: + self.done: list[str] = [] + # IDs of what the earlier steps created, by kind, for the error. + self.created: dict[str, list[str]] = {} + + def step(self, what: str, fn): + from adloop.safety.outcomes import PartialApplyError + + try: + return fn() + except PartialApplyError as exc: + if self.done: + raise PartialApplyError( + f"{exc} (after: {'; '.join(self.done)})", + created={**self.created, **exc.created, "done": list(self.done)}, unknown=exc.unknown, + ) from None + raise + except Exception as exc: + if self.done: + raise PartialApplyError( + f"{what} failed after these steps succeeded: {'; '.join(self.done)}. " + f"Microsoft said: {exc}. Check the account before drafting again.", + created={**self.created, "done": list(self.done)}, + ) from None + raise + + +def _plan(operation: str, entity_type: str, entity_id: str, account: str, customer: str, changes: dict, + payload: dict | None = None, *, warnings: list[str] | None = None, double: bool = False) -> dict: + """Store a plan: ``changes`` for the person approving, ``payload`` for the dry run and the apply.""" + return store_plan_preview( + operation, entity_type, entity_id, account, changes, + {"ad_account_id": account, "customer_id": customer, **(payload or {})}, + warnings=warnings, double=double, + ) + + +def _chunks(items: list, size: int = _CHUNK) -> list[list]: + return [items[i : i + size] for i in range(0, len(items), size)] + + +# --------------------------------------------------------------------------- +# Bidding +# --------------------------------------------------------------------------- + + +def bidding_scheme(strategy: str, *, target_cpa: float | None, max_cpc: float | None) -> dict: + scheme: dict[str, Any] = {"Type": strategy} + if strategy == "MaxConversions" and target_cpa is not None: + scheme["TargetCpa"] = round(float(target_cpa), 2) + if strategy in _CAPPED and max_cpc is not None: + scheme["MaxCpc"] = {"Amount": round(float(max_cpc), 2)} + return scheme + + +def _strategy_name(scheme: dict | None) -> str: + return str((scheme or {}).get("Type") or "").replace("BiddingScheme", "") + + +def _counted_goals(config: AdLoopConfig, account: str, customer: str) -> int: + try: + goals = _conversion_goals(config, account, customer) + except MicrosoftAdsApiError: + return -1 + return sum(1 for g in goals if g.get("Status") == "Active" and not g.get("ExcludeFromBidding")) + + +def _no_goal_refusal(strategy: str) -> str: + return ( + f"{strategy} needs an active conversion goal that counts toward Conversions, and this account has " + "none: Microsoft refuses the campaign (ConversionGoalCriteriaNotMetForBiddingScheme). Set up a " + "conversion goal first (get_microsoft_conversion_setup shows what exists), or use " + f"{_ALTERNATIVES} for now." + ) + + +def _goals_unknown_warning(strategy: str) -> str: + return (f"The conversion goals could not be read; Microsoft refuses {strategy} without an active " + "conversion goal that counts toward Conversions.") + + +def _broad_refusal(count: int, strategy: str) -> str: + return ( + f"The campaign has {count} active broad-match keyword(s), and broad match needs conversion-based " + f"bidding (MaxConversions, MaxConversionValue or a target CPA/ROAS); {strategy} would buy whatever " + "a loose match brings. Change them to phrase or exact first." + ) + + +# --------------------------------------------------------------------------- +# Shared by several areas +# --------------------------------------------------------------------------- + +def _active_broad_keywords(config, account: str, customer: str, campaign_id: str) -> list[dict]: + return [ + k for g in _ad_groups(config, account, customer, campaign_id) + for k in _keywords(config, account, customer, str(g.get("Id"))) + if k.get("MatchType") == "Broad" and k.get("Status") == "Active" + ] + + +def _check_bid(current: float | None, proposed: float | None, config) -> None: + """Bid-increase cap against the current effective bid (raises SafetyViolation).""" + from adloop.safety.guards import check_bid_increase + + if current and proposed is not None: + check_bid_increase(float(current), float(proposed), config.safety) + + +def _require_unchanged(entity: dict, before: dict, what: str) -> None: + for key, value in (before or {}).items(): + if not _same(entity.get(key), value): + raise ValueError(f"The {what}'s {key} changed since the draft; draft again.") + + +class Step: + """What a dry-run check or an apply works with: the plan, its payload, the account, the checks.""" + + def __init__(self, config: AdLoopConfig, plan: ChangePlan): + self.config = config + self.plan = plan + self.c = plan.apply_payload() + self.account = self.c["ad_account_id"] + self.customer = self.c.get("customer_id", "") + self.checks: dict[str, Any] = {"ad_account_id": self.account} + + def entity(self, kind: str, eid: str) -> dict: + """The entity and its parents, read again; refuses one that is gone. + + The plan's stored campaign and ad group keep this to three reads, not + a scan of every ad group in the account. + """ + parent = self.c.get("ad_group_id", "") if kind in ("keyword", "ad") else "" + found = find_entity(self.config, self.account, self.customer, kind, eid, parent_id=parent or "", + campaign_id=self.c.get("campaign_id", "") if kind != "campaign" else "") + if not found: + raise ValueError(f"{kind.replace('_', ' ')} '{eid}' no longer exists.") + return found + + +class Handler(NamedTuple): + """One operation: its dry-run check (sends nothing) and its apply.""" + + preflight: Callable[[Step], None] + apply: Callable[[Step, _Progress], dict] diff --git a/src/adloop/microsoft_ads/manage/ad_groups.py b/src/adloop/microsoft_ads/manage/ad_groups.py new file mode 100644 index 00000000..7e9955b7 --- /dev/null +++ b/src/adloop/microsoft_ads/manage/ad_groups.py @@ -0,0 +1,400 @@ +"""Ad groups, keywords and keyword bids.""" + +from __future__ import annotations + +import copy +from typing import TYPE_CHECKING, Any + +from adloop.microsoft_ads.manage._common import ( + _CONVERSION_BASED, + _MANUAL, + MATCH_TYPES, + NETWORKS, + Handler, + Step, + _call, + _check_bid, + _chunks, + _ctx, + _plan, + _Progress, + _require_unchanged, + _same, + _strategy_name, +) +from adloop.microsoft_ads.read import ( + _ad_groups, + _keywords, + _money, +) +from adloop.microsoft_ads.write import _blocked as _guard +from adloop.microsoft_ads.write import ( + _validation_error, + find_entity, +) + +if TYPE_CHECKING: + from adloop.config import AdLoopConfig + + +def _keyword_rows(keywords: list, errors: list[str], *, default_match: str = "Phrase") -> list[dict]: + rows = [] + for i, k in enumerate(keywords or []): + if isinstance(k, str): + k = {"text": k} + if not isinstance(k, dict): + errors.append(f"keywords[{i}] must be text or {{text, match_type, bid}}.") + continue + text = str(k.get("text") or "").strip() + match = str(k.get("match_type") or default_match).strip().title() + if not text or len(text) > 100: + errors.append(f"keywords[{i}] text is 1–100 characters.") + if match not in MATCH_TYPES: + errors.append(f"keywords[{i}].match_type must be one of {list(MATCH_TYPES)}.") + row: dict[str, Any] = {"Text": text, "MatchType": match, "Status": "Active"} + if k.get("bid") is not None: + row["Bid"] = {"Amount": round(float(k["bid"]), 2)} + rows.append(row) + return rows + + +def _refuse_broad_without_conversion_bidding(rows: list[dict], campaign: dict, errors: list[str]) -> None: + strategy = _strategy_name(campaign.get("BiddingScheme")) + broad = [r["Text"] for r in rows if r["MatchType"] == "Broad"] + if broad and strategy not in _CONVERSION_BASED: + errors.append( + f"Broad match needs conversion-based bidding (MaxConversions, MaxConversionValue or a target " + f"CPA/ROAS); on a {strategy or 'manual'} campaign it buys whatever a loose match brings. Use Phrase " + f"or Exact for {broad[:5]}, or move the campaign to MaxConversions first." + ) + + +def draft_microsoft_ad_group( + config: AdLoopConfig, + *, + ad_account_id: str = "", + campaign_id: str = "", + name: str = "", + cpc_bid: float | None = None, + network: str = "OwnedAndOperatedOnly", + keywords: list | None = None, +) -> dict: + """Draft a new ad group (with optional keywords) in a campaign.""" + operation = "microsoft_create_ad_group" + blocked = _guard(operation, config) + if blocked: + return blocked + errors: list[str] = [] + name = (name or "").strip() + if not name or len(name) > 256: + errors.append("name is required (at most 256 characters).") + if network not in NETWORKS: + errors.append(f"network must be one of {list(NETWORKS)}.") + rows = _keyword_rows(keywords or [], errors) + if errors: + return _validation_error(errors) + meta, account, customer = _ctx(config, ad_account_id) + found = find_entity(config, account, customer, "campaign", str(campaign_id)) + if not found: + return {"error": f"Microsoft campaign '{campaign_id}' was not found in account {account}."} + campaign = found["entity"] + strategy = _strategy_name(campaign.get("BiddingScheme")) + if strategy in _MANUAL and cpc_bid is None: + errors.append(f"A {strategy} campaign needs cpc_bid for the ad group.") + _refuse_broad_without_conversion_bidding(rows, campaign, errors) + names = {str(g.get("Name")).lower() for g in _ad_groups(config, account, customer, str(campaign_id))} + if name.lower() in names: + errors.append(f"The campaign already has an ad group named '{name}'.") + if errors: + return _validation_error(errors) + group: dict[str, Any] = {"Name": name, "Network": network, "Status": "Active"} + if cpc_bid is not None: + group["CpcBid"] = {"Amount": round(float(cpc_bid), 2)} + warnings = ["The ad group is active but serves only once an ad in it is enabled (new ads are created paused)."] + if network == "OwnedAndOperatedAndSyndicatedSearch": + warnings.append("Syndicated search partners are included; their traffic is usually weaker.") + return _plan( + operation, "ad_group", "", account, customer, + {"entity_name": name, "campaign_name": campaign.get("Name"), "campaign_status": campaign.get("Status"), + "cpc_bid": _money(group.get("CpcBid")), "network": network, + "status_on_create": "Active (its keywords too); nothing serves until an ad in it is enabled", + "currency": meta["currency"], + "keywords": [f"{r['Text']} [{r['MatchType']}]" + (f" bid {r['Bid']['Amount']}" if r.get("Bid") else "") + for r in rows] or None}, + {"campaign_id": str(campaign_id), "ad_group": group, "keyword_rows": rows}, + warnings=warnings, + ) + + +def update_microsoft_ad_group( + config: AdLoopConfig, + *, + ad_account_id: str = "", + ad_group_id: str = "", + name: str = "", + cpc_bid: float | None = None, + network: str = "", + audience_ads_bid_adjustment: int | None = None, +) -> dict: + """Draft ad group changes: name, default bid, search network, Audience Network bid adjustment.""" + from adloop.safety.guards import SafetyViolation, check_bid_increase + + operation = "microsoft_update_ad_group" + blocked = _guard(operation, config) + if blocked: + return blocked + errors: list[str] = [] + if network and network not in NETWORKS: + errors.append(f"network must be one of {list(NETWORKS)}.") + if audience_ads_bid_adjustment is not None and not -100 <= int(audience_ads_bid_adjustment) <= 900: + errors.append("audience_ads_bid_adjustment is -100 (off) to 900.") + if errors: + return _validation_error(errors) + meta, account, customer = _ctx(config, ad_account_id) + found = find_entity(config, account, customer, "ad_group", str(ad_group_id)) + if not found: + return {"error": f"Microsoft ad group '{ad_group_id}' was not found in account {account}."} + group, campaign = found["entity"], found["campaign"] + update: dict[str, Any] = {"Id": str(ad_group_id)} + shown: dict[str, Any] = {} + touched: list[str] = [] + warnings: list[str] = [] + if name and name.strip() != group.get("Name"): + update["Name"] = name.strip() + shown["name"] = {"from": group.get("Name"), "to": name.strip()} + touched.append("Name") + if cpc_bid is not None: + old = _money(group.get("CpcBid")) + try: + if old: + check_bid_increase(old, float(cpc_bid), config.safety) + except SafetyViolation as e: + return {"error": str(e)} + update["CpcBid"] = {"Amount": round(float(cpc_bid), 2)} + shown["cpc_bid"] = {"from": old, "to": round(float(cpc_bid), 2), "currency": meta["currency"]} + touched.append("CpcBid") + if _strategy_name(campaign.get("BiddingScheme")) not in _MANUAL: + warnings.append("The campaign uses automated bidding, which ignores the ad group's default bid.") + if network and network != group.get("Network"): + update["Network"] = network + shown["network"] = {"from": group.get("Network"), "to": network} + touched.append("Network") + adjust = None + if audience_ads_bid_adjustment is not None and int(audience_ads_bid_adjustment) != group.get("AudienceAdsBidAdjustment"): + from adloop.microsoft_ads.read import audience_network + + adjust = int(audience_ads_bid_adjustment) + update["AudienceAdsBidAdjustment"] = adjust + now = audience_network(group, campaign) + was = ("off" if not now["on"] else f"{now['bid_adjustment'] or 0:+d}%") + f" (set on the {now['set_on']})" + shown["audience_network"] = {"from": was, "to": adjust, + "meaning": "off" if adjust == -100 else f"{adjust:+d}% bids on the Audience Network"} + touched.append("AudienceAdsBidAdjustment") + if len(update) == 1: + return {"error": "Nothing to change: pass at least one setting that differs from the ad group."} + return _plan( + operation, "ad_group", str(ad_group_id), account, customer, + {"entity_name": group.get("Name"), "campaign_name": campaign.get("Name"), "changes": shown}, + {"campaign_id": str(campaign.get("Id")), "update": update, "update_audience_adjustment": adjust is not None, + "before": {k: copy.deepcopy(group.get(k)) for k in sorted(set(touched))}}, + warnings=warnings, + ) + + +def draft_microsoft_keywords( + config: AdLoopConfig, *, ad_account_id: str = "", ad_group_id: str = "", keywords: list | None = None, +) -> dict: + """Draft keyword additions to an ad group (duplicates skipped, broad refused on manual bids).""" + operation = "microsoft_add_keywords" + blocked = _guard(operation, config) + if blocked: + return blocked + errors: list[str] = [] + rows = _keyword_rows(keywords or [], errors) + if not rows and not errors: + errors.append("keywords needs at least one keyword.") + if errors: + return _validation_error(errors) + meta, account, customer = _ctx(config, ad_account_id) + found = find_entity(config, account, customer, "ad_group", str(ad_group_id)) + if not found: + return {"error": f"Microsoft ad group '{ad_group_id}' was not found in account {account}."} + group, campaign = found["entity"], found["campaign"] + _refuse_broad_without_conversion_bidding(rows, campaign, errors) + if errors: + return _validation_error(errors) + existing = {(str(k.get("Text")).lower(), k.get("MatchType")) for k in _keywords(config, account, customer, str(ad_group_id)) + if k.get("Status") != "Deleted"} + seen: set = set() + new_rows, skipped = [], [] + for r in rows: + key = (r["Text"].lower(), r["MatchType"]) + if key in existing or key in seen: + skipped.append(f"{r['Text']} [{r['MatchType']}]") + continue + seen.add(key) + new_rows.append(r) + if not new_rows: + return {"error": "Every keyword is already in the ad group.", "skipped": skipped} + warnings = [f"Skipped, already in the ad group: {skipped}."] if skipped else [] + if group.get("Status") != "Active" or campaign.get("Status") != "Active": + warnings.append(f"The ad group is {group.get('Status')} and the campaign {campaign.get('Status')}: the keywords serve once both are active.") + else: + # Keywords are created Active, as Google Ads keywords are: in a live + # ad group they can serve the moment this is applied. + warnings.append("The keywords are added Active and the ad group and campaign are active, so they can serve " + "as soon as this is applied (once the ad group has an enabled ad).") + return _plan( + operation, "ad_group", str(ad_group_id), account, customer, + {"entity_name": group.get("Name"), "campaign_name": campaign.get("Name"), "status_on_create": "Active", + "ad_group_status": group.get("Status"), "campaign_status": campaign.get("Status"), + "keywords": [f"{r['Text']} [{r['MatchType']}]" + (f" bid {r['Bid']['Amount']}" if r.get("Bid") else "") + for r in new_rows]}, + {"campaign_id": str(campaign.get("Id")), "keyword_rows": new_rows}, + warnings=warnings, + ) + + +def update_microsoft_keyword_bids( + config: AdLoopConfig, *, ad_account_id: str = "", ad_group_id: str = "", bids: list | None = None, +) -> dict: + """Draft keyword bid changes in one ad group (capped by max_bid_increase_pct).""" + from adloop.safety.guards import SafetyViolation + + operation = "microsoft_update_keyword_bids" + blocked = _guard(operation, config) + if blocked: + return blocked + errors: list[str] = [] + wanted: dict[str, float | None] = {} + for i, b in enumerate(bids or []): + if not isinstance(b, dict) or not b.get("keyword_id"): + errors.append(f"bids[{i}] needs keyword_id and bid (null removes the keyword's own bid).") + continue + wanted[str(b["keyword_id"])] = None if b.get("bid") is None else round(float(b["bid"]), 2) + if not wanted and not errors: + errors.append("bids needs at least one {keyword_id, bid}.") + if errors: + return _validation_error(errors) + meta, account, customer = _ctx(config, ad_account_id) + found = find_entity(config, account, customer, "ad_group", str(ad_group_id)) + if not found: + return {"error": f"Microsoft ad group '{ad_group_id}' was not found in account {account}."} + group, campaign = found["entity"], found["campaign"] + keywords = {str(k.get("Id")): k for k in _keywords(config, account, customer, str(ad_group_id))} + missing = [k for k in wanted if k not in keywords] + if missing: + return _validation_error([f"Keyword(s) {missing} are not in ad group '{group.get('Name')}'."]) + default_bid = _money(group.get("CpcBid")) + rows, shown, before = [], [], {} + for kid, bid in wanted.items(): + current = _money(keywords[kid].get("Bid")) or default_bid + # Removing a keyword's own bid makes it inherit the ad group default: + # that is a bid change too, and it is capped the same way. + effective = bid if bid is not None else default_bid + try: + _check_bid(current, effective, config) + except SafetyViolation as e: + return {"error": f"{keywords[kid].get('Text')}: {e}"} + rows.append({"Id": kid, "Bid": {"Amount": bid}}) + shown.append({"keyword": f"{keywords[kid].get('Text')} [{keywords[kid].get('MatchType')}]", + "from": current, "to": bid if bid is not None else f"ad group default {default_bid}"}) + before[kid] = copy.deepcopy(keywords[kid].get("Bid")) + return _plan( + operation, "ad_group", str(ad_group_id), account, customer, + {"entity_name": group.get("Name"), "currency": meta["currency"], "bids": shown}, + {"campaign_id": str(campaign.get("Id")), "keyword_rows": rows, "before": before, + "default_bid_before": copy.deepcopy(group.get("CpcBid"))}, + ) + + +def _check_create_ad_group(s: Step) -> None: + config, c, account, customer = s.config, s.c, s.account, s.customer + campaign = s.entity("campaign", c["campaign_id"])["entity"] + if c["entity_name"].lower() in {str(g.get("Name")).lower() for g in _ad_groups(config, account, customer, c["campaign_id"])}: + raise ValueError(f"An ad group named '{c['entity_name']}' now exists in the campaign.") + errors = [] + _refuse_broad_without_conversion_bidding(c["keyword_rows"], campaign, errors) + if _strategy_name(campaign.get("BiddingScheme")) in _MANUAL and not c["ad_group"].get("CpcBid"): + errors.append("The campaign now uses manual bidding, which needs a default bid for the ad group.") + if errors: + raise ValueError("; ".join(errors)) + + +def _apply_create_ad_group(s: Step, progress: _Progress) -> dict: + config, c = s.config, s.c + payload = _call(config, c, "POST", "AdGroups", {"CampaignId": c["campaign_id"], "AdGroups": [c["ad_group"]]}, "new ad group") + ad_group_id = str((payload.get("AdGroupIds") or [None])[0]) + progress.done.append(f"created ad group {ad_group_id}") + for chunk in _chunks(c["keyword_rows"], 1000): + progress.step("Adding its keywords", lambda chunk=chunk: _call( + config, c, "POST", "Keywords", {"AdGroupId": ad_group_id, "Keywords": chunk}, "keywords")) + return {"ad_group_id": ad_group_id, "name": c["entity_name"], "keywords_added": len(c["keyword_rows"])} + + +def _check_update_ad_group(s: Step) -> None: + config, plan, c = s.config, s.plan, s.c + group = s.entity("ad_group", plan.entity_id)["entity"] + _require_unchanged(group, c["before"], "ad group") + if "CpcBid" in c["update"]: + _check_bid(_money(group.get("CpcBid")), c["update"]["CpcBid"]["Amount"], config) + + +def _apply_update_ad_group(s: Step, progress: _Progress) -> dict: + config, plan, c = s.config, s.plan, s.c + _call(config, c, "PUT", "AdGroups", {"CampaignId": c["campaign_id"], "AdGroups": [c["update"]], + "UpdateAudienceAdsBidAdjustment": bool(c.get("update_audience_adjustment"))}, + "ad group update") + return {"ad_group_id": plan.entity_id, "updated": sorted(k for k in c["update"] if k != "Id")} + + +def _check_add_keywords(s: Step) -> None: + config, plan, c, account, customer = s.config, s.plan, s.c, s.account, s.customer + found = s.entity("ad_group", plan.entity_id) + errors = [] + _refuse_broad_without_conversion_bidding(c["keyword_rows"], found["campaign"], errors) + if errors: + raise ValueError("; ".join(errors)) + have = {(str(k.get("Text")).lower(), k.get("MatchType")) for k in _keywords(config, account, customer, plan.entity_id) + if k.get("Status") != "Deleted"} + again = [r["Text"] for r in c["keyword_rows"] if (r["Text"].lower(), r["MatchType"]) in have] + if again: + raise ValueError(f"Keyword(s) {again} are in the ad group now (an earlier attempt may have added them).") + + +def _apply_add_keywords(s: Step, progress: _Progress) -> dict: + config, plan, c = s.config, s.plan, s.c + payload = _call(config, c, "POST", "Keywords", {"AdGroupId": plan.entity_id, "Keywords": c["keyword_rows"]}, "keywords") + return {"ad_group_id": plan.entity_id, "keyword_ids": [str(i) for i in payload.get("KeywordIds") or []]} + + +def _check_update_keyword_bids(s: Step) -> None: + config, plan, c, account, customer = s.config, s.plan, s.c, s.account, s.customer + group = s.entity("ad_group", plan.entity_id)["entity"] + if not _same(group.get("CpcBid"), c.get("default_bid_before")): + raise ValueError("The ad group's default bid changed since the draft; draft again.") + now = {str(k.get("Id")): k.get("Bid") for k in _keywords(config, account, customer, plan.entity_id)} + for kid, bid in (c["before"] or {}).items(): + if kid not in now: + raise ValueError(f"Keyword {kid} no longer exists.") + if not _same(now[kid], bid): + raise ValueError(f"Keyword {kid}'s bid changed since the draft; draft again.") + default = _money(group.get("CpcBid")) + for row in c["keyword_rows"]: + current = _money(now[str(row["Id"])]) or default + proposed = row["Bid"]["Amount"] if row["Bid"]["Amount"] is not None else default + _check_bid(current, proposed, config) + + +def _apply_update_keyword_bids(s: Step, progress: _Progress) -> dict: + config, plan, c = s.config, s.plan, s.c + _call(config, c, "PUT", "Keywords", {"AdGroupId": plan.entity_id, "Keywords": c["keyword_rows"]}, "keyword bids") + return {"ad_group_id": plan.entity_id, "keywords_updated": len(c["keyword_rows"])} + + +HANDLERS = { + "microsoft_create_ad_group": Handler(_check_create_ad_group, _apply_create_ad_group), + "microsoft_update_ad_group": Handler(_check_update_ad_group, _apply_update_ad_group), + "microsoft_add_keywords": Handler(_check_add_keywords, _apply_add_keywords), + "microsoft_update_keyword_bids": Handler(_check_update_keyword_bids, _apply_update_keyword_bids), +} diff --git a/src/adloop/microsoft_ads/manage/ads.py b/src/adloop/microsoft_ads/manage/ads.py new file mode 100644 index 00000000..b61df66d --- /dev/null +++ b/src/adloop/microsoft_ads/manage/ads.py @@ -0,0 +1,209 @@ +"""Responsive search ads.""" + +from __future__ import annotations + +import copy +from typing import TYPE_CHECKING, Any + +from adloop.microsoft_ads.manage._common import ( + _PINS, + Handler, + Step, + _call, + _check_url, + _ctx, + _plan, + _Progress, + _require_unchanged, +) +from adloop.microsoft_ads.read import ( + _ads, +) +from adloop.microsoft_ads.write import _blocked as _guard +from adloop.microsoft_ads.write import ( + _validation_error, + find_entity, +) + +if TYPE_CHECKING: + from adloop.config import AdLoopConfig + + +def _assets(items: list, limit: int, slots: tuple, field: str, errors: list[str]) -> list[dict]: + links = [] + for i, item in enumerate(items or []): + text, pin = (item.get("text"), item.get("pinned_field")) if isinstance(item, dict) else (item, None) + text = str(text or "").strip() + if not text or len(text) > limit: + errors.append(f"{field}[{i}] is 1–{limit} characters (got {len(text)}): '{text}'.") + link: dict[str, Any] = {"Asset": {"Type": "TextAsset", "Text": text}} + if pin: + normalized = _PINS.get(str(pin).strip().lower().replace(" ", "_")) + if normalized not in slots: + errors.append(f"{field}[{i}].pinned_field must be one of {list(slots)}.") + link["PinnedField"] = normalized + links.append(link) + texts = [l["Asset"]["Text"].lower() for l in links] + if len(set(texts)) != len(texts): + errors.append(f"{field} repeat the same text.") + for slot in slots: + pinned = [l for l in links if l.get("PinnedField") == slot] + unpinned = [l for l in links if not l.get("PinnedField")] + if not pinned and not unpinned: + errors.append(f"Nothing can fill {slot}: pin an asset there or leave some unpinned.") + return links + + +def _rsa_fields(headlines, descriptions, final_url, path1, path2, errors, warnings, *, partial: bool) -> dict: + fields: dict[str, Any] = {} + if headlines is not None or not partial: + h = _assets(headlines or [], 30, ("Headline1", "Headline2", "Headline3"), "headlines", errors) + if not 3 <= len(h) <= 15: + errors.append(f"An RSA takes 3–15 headlines (got {len(h)}).") + fields["Headlines"] = h + if descriptions is not None or not partial: + d = _assets(descriptions or [], 90, ("Description1", "Description2"), "descriptions", errors) + if not 2 <= len(d) <= 4: + errors.append(f"An RSA takes 2–4 descriptions (got {len(d)}).") + fields["Descriptions"] = d + if final_url or not partial: + _check_url((final_url or "").strip(), errors, warnings) + fields["FinalUrls"] = [(final_url or "").strip()] + for name, value in (("Path1", path1), ("Path2", path2)): + if value is None: + continue + value = value.strip() + if len(value) > 15 or "/" in value: + errors.append(f"{name.lower()} is at most 15 characters, without '/'.") + fields[name] = value + if fields.get("Path2") and not (fields.get("Path1") or (partial and path1 is None)): + errors.append("path2 needs path1.") + if not partial and fields.get("Headlines") and len(fields["Headlines"]) < 8: + warnings.append("8–15 distinct headlines give Microsoft more combinations to test.") + pins = [l for l in fields.get("Headlines", []) + fields.get("Descriptions", []) if l.get("PinnedField")] + if pins: + warnings.append(f"{len(pins)} asset(s) are pinned; pinning limits the combinations Microsoft can show.") + return fields + + +def draft_microsoft_responsive_search_ad( + config: AdLoopConfig, *, ad_account_id: str = "", ad_group_id: str = "", headlines: list | None = None, + descriptions: list | None = None, final_url: str = "", path1: str = "", path2: str = "", +) -> dict: + """Draft a responsive search ad, created PAUSED.""" + operation = "microsoft_create_rsa" + blocked = _guard(operation, config) + if blocked: + return blocked + errors: list[str] = [] + warnings: list[str] = [] + fields = _rsa_fields(headlines, descriptions, final_url, path1, path2, errors, warnings, partial=False) + if errors: + return _validation_error(errors) + meta, account, customer = _ctx(config, ad_account_id) + found = find_entity(config, account, customer, "ad_group", str(ad_group_id)) + if not found: + return {"error": f"Microsoft ad group '{ad_group_id}' was not found in account {account}."} + group, campaign = found["entity"], found["campaign"] + ad = {"Type": "ResponsiveSearch", "Status": "Paused", **fields} + for key in ("Path1", "Path2"): + if not ad.get(key): + ad.pop(key, None) + if "Path1" not in ad: + ad.pop("Path2", None) + warnings.append("No display paths: path1/path2 make the display URL more specific.") + return _plan( + operation, "ad_group", str(ad_group_id), account, customer, + {"entity_name": group.get("Name"), "campaign_name": campaign.get("Name"), "status_on_create": "Paused", + "headlines": [l["Asset"]["Text"] + (f" [pinned {l['PinnedField']}]" if l.get("PinnedField") else "") + for l in fields["Headlines"]], + "descriptions": [l["Asset"]["Text"] for l in fields["Descriptions"]], + "final_url": fields["FinalUrls"][0], "path1": ad.get("Path1"), "path2": ad.get("Path2")}, + {"campaign_id": str(campaign.get("Id")), "ad": ad}, + warnings=warnings, + ) + + +def update_microsoft_responsive_search_ad( + config: AdLoopConfig, *, ad_account_id: str = "", ad_id: str = "", headlines: list | None = None, + descriptions: list | None = None, final_url: str = "", path1: str | None = None, path2: str | None = None, +) -> dict: + """Draft RSA changes: headlines or descriptions (each list replaced whole), landing page, paths.""" + operation = "microsoft_update_rsa" + blocked = _guard(operation, config) + if blocked: + return blocked + errors: list[str] = [] + warnings: list[str] = [] + fields = _rsa_fields(headlines, descriptions, final_url, path1, path2, errors, warnings, partial=True) + if errors: + return _validation_error(errors) + if not fields: + return {"error": "Nothing to change: pass headlines, descriptions, final_url, path1 or path2."} + meta, account, customer = _ctx(config, ad_account_id) + found = find_entity(config, account, customer, "ad", str(ad_id)) + if not found: + return {"error": f"Microsoft ad '{ad_id}' was not found in account {account}."} + ad, group, campaign = found["entity"], found["ad_group"], found["campaign"] + if ad.get("Type") != "ResponsiveSearch": + return _validation_error([f"Ad {ad_id} is a {ad.get('Type')} ad; only responsive search ads are edited here."]) + shown = {} + for key, value in fields.items(): + if key in ("Headlines", "Descriptions"): + shown[key.lower()] = {"from": [l.get("Asset", {}).get("Text") for l in ad.get(key) or []], + "to": [l["Asset"]["Text"] for l in value]} + else: + shown[key.lower()] = {"from": ad.get(key), "to": value} + warnings.append("Edited ads go back to Microsoft's editorial review.") + return _plan( + operation, "ad", str(ad_id), account, customer, + {"entity_name": f"RSA {ad_id}", "ad_group_name": group.get("Name"), "campaign_name": campaign.get("Name"), + "changes": shown}, + {"campaign_id": str(campaign.get("Id")), "ad_group_id": str(group.get("Id")), + "update": {"Type": "ResponsiveSearch", "Id": str(ad_id), **fields}, + "before": {k: copy.deepcopy(ad.get(k)) for k in fields}}, + warnings=warnings, + ) + + +def _check_create_rsa(s: Step) -> None: + config, plan, c, account, customer = s.config, s.plan, s.c, s.account, s.customer + found = s.entity("ad_group", plan.entity_id) + errors: list[str] = [] + _check_url(c["final_url"], errors, []) + if errors: + raise ValueError("; ".join(errors)) + wanted = sorted(l["Asset"]["Text"] for l in c["ad"]["Headlines"]) + for ad in _ads(config, account, customer, plan.entity_id): + if sorted(str(l.get("Asset", {}).get("Text")) for l in ad.get("Headlines") or []) == wanted: + raise ValueError(f"Ad group '{found['entity'].get('Name')}' already has an RSA with these headlines (ad {ad.get('Id')}).") + + +def _apply_create_rsa(s: Step, progress: _Progress) -> dict: + config, plan, c = s.config, s.plan, s.c + payload = _call(config, c, "POST", "Ads", {"AdGroupId": plan.entity_id, "Ads": [c["ad"]]}, "responsive search ad") + return {"ad_id": str((payload.get("AdIds") or [None])[0]), "status": "Paused", + "next": "Enable it with enable_microsoft_entity once reviewed."} + + +def _check_update_rsa(s: Step) -> None: + plan, c = s.plan, s.c + found = s.entity("ad", plan.entity_id) + _require_unchanged(found["entity"], c["before"], "ad") + if c["update"].get("FinalUrls"): + errors = [] + _check_url(c["update"]["FinalUrls"][0], errors, []) + if errors: + raise ValueError("; ".join(errors)) + + +def _apply_update_rsa(s: Step, progress: _Progress) -> dict: + config, plan, c = s.config, s.plan, s.c + _call(config, c, "PUT", "Ads", {"AdGroupId": c["ad_group_id"], "Ads": [c["update"]]}, "responsive search ad update") + return {"ad_id": plan.entity_id, "updated": sorted(k for k in c["update"] if k not in ("Id", "Type"))} + + +HANDLERS = { + "microsoft_create_rsa": Handler(_check_create_rsa, _apply_create_rsa), + "microsoft_update_rsa": Handler(_check_update_rsa, _apply_update_rsa), +} diff --git a/src/adloop/microsoft_ads/manage/campaigns.py b/src/adloop/microsoft_ads/manage/campaigns.py new file mode 100644 index 00000000..900b3932 --- /dev/null +++ b/src/adloop/microsoft_ads/manage/campaigns.py @@ -0,0 +1,334 @@ +"""Campaign settings (name, bid strategy, tracking) and new Search campaigns.""" + +from __future__ import annotations + +import copy +from typing import TYPE_CHECKING, Any + +from adloop.microsoft_ads.manage._common import ( + _CAPPED, + _CONVERSION_BASED, + INTENTS, + STRATEGIES, + Handler, + Step, + _active_broad_keywords, + _broad_refusal, + _call, + _check_bid, + _chunks, + _clean, + _counted_goals, + _ctx, + _goals_unknown_warning, + _no_goal_refusal, + _plan, + _Progress, + _require_unchanged, + _strategy_name, + bidding_scheme, +) +from adloop.microsoft_ads.read import ( + _bidding, + _campaigns, +) +from adloop.microsoft_ads.write import _blocked as _guard +from adloop.microsoft_ads.write import ( + _validation_error, + find_entity, +) +from adloop.safety.guards import check_budget_cap + +if TYPE_CHECKING: + from adloop.config import AdLoopConfig + + +def update_microsoft_campaign( + config: AdLoopConfig, + *, + ad_account_id: str = "", + campaign_id: str = "", + name: str = "", + bidding_strategy: str = "", + target_cpa: float | None = None, + max_cpc: float | None = None, + tracking_url_template: str | None = None, + final_url_suffix: str | None = None, +) -> dict: + """Draft campaign setting changes: name, bid strategy, tracking template, final URL suffix.""" + operation = "microsoft_update_campaign" + blocked = _guard(operation, config) + if blocked: + return blocked + errors: list[str] = [] + campaign_id = str(campaign_id or "").strip() + if not campaign_id: + errors.append("campaign_id is required") + if name and len(name.strip()) > 128: + errors.append("name is at most 128 characters.") + strategy = (bidding_strategy or "").strip() + if strategy == "TargetCpa": + strategy = "MaxConversions" + if strategy and strategy not in STRATEGIES: + errors.append(f"bidding_strategy must be one of {list(STRATEGIES)}.") + if target_cpa is not None and (strategy or "") not in ("", "MaxConversions"): + errors.append("target_cpa goes with MaxConversions.") + if max_cpc is not None and strategy and strategy not in _CAPPED: + errors.append(f"max_cpc caps {' or '.join(sorted(_CAPPED))} bids; a {strategy} campaign's bids are set " + "on its ad groups and keywords.") + template = None if tracking_url_template is None else tracking_url_template.strip() + if template and not template.startswith(("http://", "https://", "{lpurl}", "{unescapedlpurl}")): + errors.append("tracking_url_template must start with {lpurl}, {unescapedlpurl}, http:// or https://.") + if errors: + return _validation_error(errors) + meta, account, customer = _ctx(config, ad_account_id) + found = find_entity(config, account, customer, "campaign", campaign_id) + if not found: + return {"error": f"Microsoft campaign '{campaign_id}' was not found in account {account}."} + campaign = found["entity"] + update: dict[str, Any] = {"Id": campaign_id} + shown: dict[str, Any] = {} + warnings: list[str] = [] + touched: list[str] = [] + if name and name.strip() != campaign.get("Name"): + others = {str(c.get("Name")).lower() for c in _campaigns(config, account, customer) if str(c.get("Id")) != campaign_id} + if name.strip().lower() in others: + return _validation_error([f"Another campaign is already named '{name.strip()}'."]) + update["Name"] = name.strip() + shown["name"] = {"from": campaign.get("Name"), "to": name.strip()} + touched.append("Name") + current_scheme = campaign.get("BiddingScheme") or {} + if strategy or target_cpa is not None or max_cpc is not None: + chosen = strategy or _strategy_name(current_scheme) + if chosen not in STRATEGIES: + return _validation_error([f"The campaign uses {chosen or 'an unknown strategy'}; pass bidding_strategy explicitly."]) + if target_cpa is not None and chosen != "MaxConversions": + return _validation_error([f"target_cpa goes with MaxConversions; this campaign uses {chosen}. Pass " + "bidding_strategy='MaxConversions' to switch."]) + if max_cpc is not None and chosen not in _CAPPED: + return _validation_error([f"max_cpc caps {' or '.join(sorted(_CAPPED))} bids; this campaign uses " + f"{chosen}, whose bids are set on its ad groups and keywords."]) + has_cap = (current_scheme.get("MaxCpc") or {}).get("Amount") is not None + if max_cpc is not None and not has_cap and chosen in _CAPPED: + return _validation_error([ + "Microsoft no longer lets a campaign add a maximum CPC to automated bidding; it can " + "only change or remove an existing one." + ]) + keep_cap = (current_scheme.get("MaxCpc") or {}).get("Amount") if chosen == _strategy_name(current_scheme) else None + scheme = bidding_scheme( + chosen, + target_cpa=target_cpa if target_cpa is not None else (current_scheme.get("TargetCpa") if chosen == "MaxConversions" and _strategy_name(current_scheme) == "MaxConversions" else None), + max_cpc=max_cpc if max_cpc is not None else keep_cap, + ) + update["BiddingScheme"] = scheme + touched.append("BiddingScheme") + shown["bidding"] = {"from": _bidding(current_scheme), "to": _bidding(scheme), "currency": meta["currency"]} + switching = chosen != _strategy_name(current_scheme) + if switching: + warnings.append("Changing the bid strategy restarts Microsoft's learning period; expect a week or two of unsettled results.") + if chosen in _CONVERSION_BASED: + goals = _counted_goals(config, account, customer) + if goals == 0 and switching: + return _validation_error([_no_goal_refusal(chosen)]) + if goals == 0: + warnings.append(f"No active conversion goal counts toward Conversions: {chosen} has nothing to optimize for.") + elif goals < 0: + warnings.append(_goals_unknown_warning(chosen)) + old_cap = (current_scheme.get("MaxCpc") or {}).get("Amount") + new_cap = (scheme.get("MaxCpc") or {}).get("Amount") + try: + _check_bid(old_cap, new_cap, config) + except Exception as e: # SafetyViolation + return {"error": f"Maximum CPC: {e}"} + if chosen not in _CONVERSION_BASED: + broad = _active_broad_keywords(config, account, customer, campaign_id) + if broad: + return _validation_error([_broad_refusal(len(broad), chosen)]) + for field, value, api_name in (("tracking_url_template", template, "TrackingUrlTemplate"), + ("final_url_suffix", None if final_url_suffix is None else final_url_suffix.strip(), "FinalUrlSuffix")): + if value is None or value == (campaign.get(api_name) or ""): + continue + update[api_name] = value + touched.append(api_name) + shown[field] = {"from": campaign.get(api_name) or None, "to": value or None} + if value == "": + warnings.append(f"{field} is removed.") + if len(update) == 1: + return {"error": "Nothing to change: pass at least one setting that differs from the campaign."} + return _plan( + operation, "campaign", campaign_id, account, customer, + {"entity_name": campaign.get("Name"), "campaign_status": campaign.get("Status"), "changes": shown}, + {"update": update, "before": {k: copy.deepcopy(campaign.get(k)) for k in sorted(set(touched))}}, + warnings=warnings, + ) + + +def draft_microsoft_campaign( + config: AdLoopConfig, + *, + ad_account_id: str = "", + name: str = "", + daily_budget: float = 0.0, + bidding_strategy: str = "MaxConversions", + target_cpa: float | None = None, + languages: list[str] | None = None, + location_ids: list[str] | None = None, + excluded_location_ids: list[str] | None = None, + location_intent: str = "PeopleIn", + tracking_url_template: str = "", + final_url_suffix: str = "", +) -> dict: + """Draft a new Search campaign, created PAUSED, with its locations and location intent.""" + from adloop.safety.guards import SafetyViolation, check_budget_cap + + operation = "microsoft_create_campaign" + blocked = _guard(operation, config) + if blocked: + return blocked + errors: list[str] = [] + name = (name or "").strip() + if not name or len(name) > 128: + errors.append("name is required (at most 128 characters).") + try: + budget = round(float(daily_budget), 2) + except (TypeError, ValueError): + budget = 0.0 + if budget <= 0: + errors.append("daily_budget must be a positive amount in the account currency.") + strategy = "MaxConversions" if bidding_strategy == "TargetCpa" else (bidding_strategy or "MaxConversions") + if strategy not in STRATEGIES: + errors.append(f"bidding_strategy must be one of {list(STRATEGIES)}.") + if target_cpa is not None and strategy != "MaxConversions": + errors.append(f"target_cpa goes with MaxConversions, not {strategy}.") + langs = _clean(languages) + if not langs: + errors.append("languages is required, e.g. ['English']: without it ads reach every language.") + elif any(lang.lower() == "all" for lang in langs): + errors.append("languages=['All'] reaches every language; name the languages the ads are written in, " + "e.g. ['English'].") + include = _clean(location_ids) + if not include: + errors.append("location_ids is required (search_microsoft_locations): an untargeted campaign serves everywhere.") + exclude = _clean(excluded_location_ids) + if any(not i.isdigit() for i in include + exclude): + errors.append("Location ids are numbers (search_microsoft_locations).") + if location_intent not in INTENTS: + errors.append(f"location_intent must be one of {list(INTENTS)}.") + if errors: + return _validation_error(errors) + try: + check_budget_cap(budget, config.safety) + except SafetyViolation as e: + return {"error": str(e)} + meta, account, customer = _ctx(config, ad_account_id) + existing = {str(c.get("Name")).lower() for c in _campaigns(config, account, customer)} + if name.lower() in existing: + return _validation_error([f"A campaign named '{name}' already exists."]) + warnings: list[str] = [] + if strategy in _CONVERSION_BASED: + goals = _counted_goals(config, account, customer) + if goals == 0: + return _validation_error([_no_goal_refusal(strategy)]) + if goals < 0: + warnings.append(_goals_unknown_warning(strategy)) + if target_cpa is not None and target_cpa > 0 and budget < 5 * target_cpa: + warnings.append(f"A daily budget below 5× the target CPA ({target_cpa}) gives bidding little to learn from.") + campaign: dict[str, Any] = { + "Name": name, + "BudgetType": "DailyBudgetStandard", + "DailyBudget": budget, + "CampaignType": "Search", + "Languages": langs, + "Status": "Paused", + "TimeZone": meta["time_zone"], + "BiddingScheme": bidding_scheme(strategy, target_cpa=target_cpa, max_cpc=None), + } + if tracking_url_template: + campaign["TrackingUrlTemplate"] = tracking_url_template.strip() + if final_url_suffix: + campaign["FinalUrlSuffix"] = final_url_suffix.strip() + criteria = ( + [{"Type": "BiddableCampaignCriterion", "Criterion": {"Type": "LocationCriterion", "LocationId": int(i)}, + "CriterionBid": {"Type": "BidMultiplier", "Multiplier": 0}} for i in include] + + [{"Type": "NegativeCampaignCriterion", "Criterion": {"Type": "LocationCriterion", "LocationId": int(i)}} + for i in exclude] + + [{"Type": "BiddableCampaignCriterion", + "Criterion": {"Type": "LocationIntentCriterion", "IntentOption": location_intent}}] + ) + # [AUD]: search campaigns reach the Microsoft Audience Network (Outlook, + # MSN) unless their AudienceAdsBidAdjustment is -100. + warnings.append("New search campaigns can also show on the Microsoft Audience Network (Outlook, MSN, Edge); " + "set audience_ads_bid_adjustment=-100 on its ad groups (update_microsoft_ad_group) to keep " + "it on search only.") + return _plan( + operation, "campaign", "", account, customer, + { + "entity_name": name, "status_on_create": "Paused", "daily_budget": budget, "currency": meta["currency"], + "monthly_maximum": round(budget * 30.4, 2), "bidding": _bidding(campaign["BiddingScheme"]), + "languages": langs, "location_ids": include, "excluded_location_ids": exclude or None, + "location_intent": location_intent, "time_zone": meta["time_zone"], + "tracking_url_template": campaign.get("TrackingUrlTemplate"), + "final_url_suffix": campaign.get("FinalUrlSuffix"), + }, + {"campaign": campaign, "criteria": criteria}, + warnings=warnings + [ + "Created paused. Add ad groups, keywords, ads and extensions, then enable it.", + ], + ) + + +def _check_update_campaign(s: Step) -> None: + config, plan, c, account, customer = s.config, s.plan, s.c, s.account, s.customer + campaign = s.entity("campaign", plan.entity_id)["entity"] + _require_unchanged(campaign, c["before"], "campaign") + scheme = c["update"].get("BiddingScheme") + if scheme: + _check_bid((((campaign.get("BiddingScheme") or {}).get("MaxCpc")) or {}).get("Amount"), + (scheme.get("MaxCpc") or {}).get("Amount"), config) + strategy = _strategy_name(scheme) + if strategy not in _CONVERSION_BASED: + broad = _active_broad_keywords(config, account, customer, plan.entity_id) + if broad: + raise ValueError(_broad_refusal(len(broad), strategy).replace("The campaign has", "The campaign now has")) + elif (strategy != _strategy_name(c["before"].get("BiddingScheme")) + and _counted_goals(config, account, customer) == 0): + raise ValueError(_no_goal_refusal(strategy)) + + +def _apply_update_campaign(s: Step, progress: _Progress) -> dict: + config, plan, c, account = s.config, s.plan, s.c, s.account + _call(config, c, "PUT", "Campaigns", {"AccountId": account, "Campaigns": [c["update"]]}, "campaign update") + return {"campaign_id": plan.entity_id, "updated": sorted(k for k in c["update"] if k != "Id")} + + +def _check_create_campaign(s: Step) -> None: + config, c, account, customer = s.config, s.c, s.account, s.customer + check_budget_cap(float(c["daily_budget"]), config.safety) + if c["entity_name"].lower() in {str(x.get("Name")).lower() for x in _campaigns(config, account, customer)}: + raise ValueError(f"A campaign named '{c['entity_name']}' now exists (an earlier attempt may have created it).") + strategy = _strategy_name(c["campaign"].get("BiddingScheme")) + if strategy in _CONVERSION_BASED: + goals = _counted_goals(config, account, customer) + if goals == 0: + raise ValueError(_no_goal_refusal(strategy)) + s.checks["conversion_goals"] = goals if goals >= 0 else "unknown" + s.checks["budget_cap_ok"] = True + + +def _apply_create_campaign(s: Step, progress: _Progress) -> dict: + config, c, account = s.config, s.c, s.account + payload = _call(config, c, "POST", "Campaigns", {"AccountId": account, "Campaigns": [c["campaign"]]}, "new campaign") + campaign_id = str((payload.get("CampaignIds") or [None])[0]) + progress.done.append(f"created campaign {campaign_id} (paused)") + criteria = [{**x, "CampaignId": campaign_id} for x in c["criteria"]] + for chunk in _chunks(criteria): + progress.step("Adding the campaign's locations", lambda chunk=chunk: _call( + config, c, "POST", "CampaignCriterions", {"CampaignCriterions": chunk, "CriterionType": "Targets"}, "locations")) + return {"campaign_id": campaign_id, "name": c["entity_name"], "status": "Paused", + "next": "Add ad groups, keywords, ads and extensions, then enable it."} + + +HANDLERS = { + "microsoft_update_campaign": Handler(_check_update_campaign, _apply_update_campaign), + "microsoft_create_campaign": Handler(_check_create_campaign, _apply_create_campaign), +} diff --git a/src/adloop/microsoft_ads/manage/extensions.py b/src/adloop/microsoft_ads/manage/extensions.py new file mode 100644 index 00000000..7c350d86 --- /dev/null +++ b/src/adloop/microsoft_ads/manage/extensions.py @@ -0,0 +1,698 @@ +"""Ad extensions: sitelinks, callouts, structured snippets, call and image extensions, and their read.""" + +from __future__ import annotations + +import base64 +import hashlib +import json +from typing import TYPE_CHECKING, Any + +from adloop.microsoft_ads.auth import MicrosoftAdsApiError +from adloop.microsoft_ads.client import campaign_request +from adloop.microsoft_ads.manage._common import ( + _EXTENSION_TYPES, + Handler, + Step, + _call, + _check_url, + _chunks, + _clean, + _ctx, + _plan, + _Progress, +) +from adloop.microsoft_ads.read import ( + _ad_groups, + _campaigns, +) +from adloop.microsoft_ads.write import _blocked as _guard +from adloop.microsoft_ads.write import ( + _validation_error, + find_entity, +) + +if TYPE_CHECKING: + from adloop.config import AdLoopConfig + +# The plan's entity_type for each Microsoft AssociationType. +_ASSOCIATION_ENTITY = {"Account": "account", "Campaign": "campaign", "AdGroup": "ad_group"} + + +def _extension_target(config, account, customer, campaign_id: str, scope: str, + ad_group_id: str = "") -> tuple[str, str, str] | dict: + """(AssociationType, entity id, label) of where an extension links; ad groups only when the caller allows them.""" + if scope == "account": + if campaign_id or ad_group_id: + given = "ad_group_id" if ad_group_id else "campaign_id" + return _validation_error([f"Pass {given} or scope='account', not both."]) + return "Account", account, f"account {account}" + if ad_group_id: + if campaign_id: + return _validation_error(["Pass campaign_id or ad_group_id, not both."]) + found = find_entity(config, account, customer, "ad_group", str(ad_group_id)) + if not found: + return {"error": f"Microsoft ad group '{ad_group_id}' was not found in account {account}."} + return ("AdGroup", str(ad_group_id), + f"ad group '{found['entity'].get('Name')}' in campaign '{found['campaign'].get('Name')}'") + if not campaign_id: + return _validation_error(["campaign_id is required (or scope='account' for every campaign without its own)."]) + found = find_entity(config, account, customer, "campaign", str(campaign_id)) + if not found: + return {"error": f"Microsoft campaign '{campaign_id}' was not found in account {account}."} + return "Campaign", str(campaign_id), f"campaign '{found['entity'].get('Name')}'" + + +def _associated_extensions(config, account, customer, association_type: str, entity_id: str | list[str]) -> list[dict]: + """Extension links of one entity or of up to 100 (Microsoft's EntityIds limit); each carries its EntityId.""" + ids = [str(i) for i in (entity_id if isinstance(entity_id, list) else [entity_id])] + body = {"AccountId": account, "AdExtensionType": _EXTENSION_TYPES, "AssociationType": association_type, + "EntityIds": [int(i) for i in ids]} + payload = campaign_request(config, "AdExtensionsAssociations/Query", body, account_id=account, customer_id=customer) + out = [] + # One collection per requested entity, in the request's order. + for owner, collection in zip(ids, payload.get("AdExtensionAssociationCollection") or [], strict=False): + for assoc in (collection or {}).get("AdExtensionAssociations") or []: + if isinstance(assoc, dict) and isinstance(assoc.get("AdExtension"), dict): + out.append({**assoc, "EntityId": str(assoc.get("EntityId") or owner)}) + return out + + +def _draft_extensions(config, *, ad_account_id, campaign_id, scope, operation, kind, extensions, shown, warnings) -> dict: + blocked = _guard(operation, config) + if blocked: + return blocked + meta, account, customer = _ctx(config, ad_account_id) + target = _extension_target(config, account, customer, str(campaign_id or ""), (scope or "").strip().lower()) + if isinstance(target, dict): + return target + association, entity_id, where = target + existing = _associated_extensions(config, account, customer, association, entity_id) + same = [a["AdExtension"] for a in existing if a["AdExtension"].get("Type") == kind] + if kind == "CallAdExtension" and same: + return _validation_error([f"{where} already has a call extension; Microsoft allows one per campaign."]) + def key(ext): # noqa: E306 + return json.dumps({k: ext.get(k) for k in ("Text", "DisplayText", "Header", "Values", "PhoneNumber")}, sort_keys=True).lower() + have = {key(e) for e in same} + new = [e for e in extensions if key(e) not in have] + if not new: + return {"error": f"Every one of these is already on {where}."} + if len(new) < len(extensions): + warnings.append(f"Skipped {len(extensions) - len(new)} already on {where}.") + return _plan( + operation, _ASSOCIATION_ENTITY[association], entity_id, account, customer, + {"entity_name": where, **shown}, + {"association_type": association, "entity_id": entity_id, "extensions": new}, + warnings=warnings, + ) + + +def draft_microsoft_sitelinks(config, *, ad_account_id="", campaign_id="", scope="", sitelinks=None) -> dict: + errors: list[str] = [] + warnings: list[str] = [] + exts = [] + for i, s in enumerate(sitelinks or []): + if not isinstance(s, dict): + errors.append(f"sitelinks[{i}] must be {{link_text, final_url, description1, description2}}.") + continue + text = str(s.get("link_text") or "").strip() + d1, d2 = str(s.get("description1") or "").strip(), str(s.get("description2") or "").strip() + limit = 25 if (d1 or d2) else 35 + if not text or len(text) > limit: + errors.append(f"sitelinks[{i}].link_text is 1–{limit} characters.") + if bool(d1) != bool(d2): + errors.append(f"sitelinks[{i}] needs both descriptions or neither.") + if len(d1) > 35 or len(d2) > 35: + errors.append(f"sitelinks[{i}] descriptions are at most 35 characters each.") + _check_url(str(s.get("final_url") or "").strip(), errors, warnings, field=f"sitelinks[{i}].final_url") + ext = {"Type": "SitelinkAdExtension", "DisplayText": text, "FinalUrls": [str(s.get("final_url") or "").strip()]} + if d1: + ext.update(Description1=d1, Description2=d2) + exts.append(ext) + if not exts and not errors: + errors.append("sitelinks needs at least one sitelink.") + if len(exts) > 20: + errors.append("At most 20 sitelinks per campaign.") + if errors: + return _validation_error(errors) + if len(exts) < 4: + warnings.append("Four or more sitelinks let Microsoft show the larger sitelink formats.") + return _draft_extensions(config, ad_account_id=ad_account_id, campaign_id=campaign_id, scope=scope, + operation="microsoft_add_sitelinks", kind="SitelinkAdExtension", extensions=exts, + shown={"sitelinks": [ + f"{e['DisplayText']} → {e['FinalUrls'][0]}" + + (f" ({e['Description1']} / {e['Description2']})" if e.get("Description1") else "") + for e in exts]}, + warnings=warnings) + + +def draft_microsoft_callouts(config, *, ad_account_id="", campaign_id="", scope="", callouts=None) -> dict: + errors: list[str] = [] + texts = _clean(callouts) + for t in texts: + if len(t) > 25: + errors.append(f"Callout '{t}' is longer than 25 characters.") + if not texts: + errors.append("callouts needs at least one callout.") + if errors: + return _validation_error(errors) + warnings = [] if len(texts) >= 2 else ["A campaign needs at least 2 callouts before Microsoft shows them."] + exts = [{"Type": "CalloutAdExtension", "Text": t} for t in dict.fromkeys(texts)] + return _draft_extensions(config, ad_account_id=ad_account_id, campaign_id=campaign_id, scope=scope, + operation="microsoft_add_callouts", kind="CalloutAdExtension", extensions=exts, + shown={"callouts": [e["Text"] for e in exts]}, warnings=warnings) + + +def draft_microsoft_structured_snippet(config, *, ad_account_id="", campaign_id="", scope="", header="", values=None) -> dict: + errors: list[str] = [] + vals = list(dict.fromkeys(_clean(values))) + if not (header or "").strip(): + errors.append("header is required (one of Microsoft's headers, e.g. Services, Brands, Types).") + if not 3 <= len(vals) <= 10: + errors.append(f"A structured snippet takes 3–10 values (got {len(vals)}).") + for v in vals: + if len(v) > 25: + errors.append(f"Value '{v}' is longer than 25 characters.") + if errors: + return _validation_error(errors) + ext = {"Type": "StructuredSnippetAdExtension", "Header": header.strip(), "Values": vals} + return _draft_extensions(config, ad_account_id=ad_account_id, campaign_id=campaign_id, scope=scope, + operation="microsoft_add_structured_snippet", kind="StructuredSnippetAdExtension", + extensions=[ext], shown={"snippet": f"{ext['Header']}: {', '.join(vals)}"}, warnings=[]) + + +def draft_microsoft_call_extension(config, *, ad_account_id="", campaign_id="", phone_number="", country_code="") -> dict: + errors: list[str] = [] + number = (phone_number or "").strip() + country = (country_code or "").strip().upper() + if not number or len(number) > 35: + errors.append("phone_number is required (at most 35 characters).") + if len(country) != 2 or not country.isalpha(): + errors.append("country_code is the two-letter country of the number, e.g. US.") + if errors: + return _validation_error(errors) + ext = {"Type": "CallAdExtension", "PhoneNumber": number, "CountryCode": country, "IsCallOnly": False} + return _draft_extensions(config, ad_account_id=ad_account_id, campaign_id=campaign_id, scope="", + operation="microsoft_add_call_extension", kind="CallAdExtension", extensions=[ext], + shown={"phone_number": number, "country_code": country}, + warnings=["Use the call-tracking number that should receive Microsoft calls."]) + + +# --------------------------------------------------------------------------- +# Image extensions +# --------------------------------------------------------------------------- +# Microsoft's limits, from its documentation (checked 2026-11-05): +# [EXT] ImageAdExtension: learn.microsoft.com/advertising/campaign-management-service/imageadextension +# [IMG] Image (media): learn.microsoft.com/advertising/campaign-management-service/image +# [ADD] AddMedia: learn.microsoft.com/advertising/campaign-management-service/addmedia +# [RSA] ResponsiveAd Remarks (same media library): +# learn.microsoft.com/advertising/campaign-management-service/responsivead#remarks +# [BULK] Image Ad Extension record: learn.microsoft.com/advertising/bulk-service/image-ad-extension +# [HELP] Add images to your ad with image extensions: +# learn.microsoft.com/advertising/msa-help/hlp_ba_proc_addimageextension +# [GUIDE] Image guidelines and policies: learn.microsoft.com/advertising/msa-help/hlp_ba_conc_imageguidelines +# [AUD] Audience ads guide: learn.microsoft.com/advertising/guides/audience-ads + +# GIF, JPEG and PNG, no animation [IMG Remarks, GUIDE]. +_IMAGE_FORMATS = {"image/jpeg": "JPEG", "image/png": "PNG", "image/gif": "GIF"} +# "1.91:1 aspect ratio is required for the extension to be eligible to serve" +# with a minimum of 703 x 368 pixels [GUIDE, HELP]; Microsoft crops the other +# placements' ratios from it. The extension links the image as its +# LandscapeImageMedia asset, which is 1.91:1 [BULK images.subType]. +_IMAGE_RATIO = 1.91 +_IMAGE_RATIO_TOLERANCE = 0.01 # 1200x628 is 1.911, 703x368 is 1.910 +_IMAGE_MIN_SIZE = (703, 368) +# "The maximum width and height in pixels are 2592 and 2048 independently" [IMG, RSA]. +_IMAGE_MAX_SIZE = (2592, 2048) +# "The maximum file size is 5 MB" [RSA Remarks]. [IMG] also names a cap of +# 102,400 base64 characters (about 75 KB) for Image.Data, but Microsoft does +# not enforce it on upload: JPEGs of 125-300 KB went through on a live +# account. The draft enforces the 5 MB limit only. +_IMAGE_MAX_BYTES = 5 * 1024 * 1024 +# "You can add a maximum of 10 media in a single call" [ADD]. +_IMAGES_PER_DRAFT = 10 +_ALT_TEXT_MAX = 35 # AlternativeText, required [EXT] +_DISPLAY_TEXT_MAX = 35 # DisplayText, required for the SearchMultiple layout [EXT] +_DESCRIPTION_MAX = 100 # Description, internal label, not shown [EXT] +# Image extensions linked to one account, campaign or ad group: 25 in [BULK] +# and [HELP], 6 in [EXT] and the "About ad extensions" association table. +_IMAGE_LINKS_MAX = 25 +_IMAGE_LINKS_LOW = 6 + + +def _gif_frames(data: bytes) -> int: + """Image frames in a GIF (2 is enough to call it animated).""" + def skip_blocks(i: int) -> int: + while data[i]: + i += data[i] + 1 + return i + 1 + + frames = 0 + try: + flags = data[10] + i = 13 + (3 * 2 ** ((flags & 0x07) + 1) if flags & 0x80 else 0) + while i < len(data) and frames < 2: + block = data[i] + if block == 0x2C: # image descriptor + frames += 1 + flags = data[i + 9] + i += 10 + (3 * 2 ** ((flags & 0x07) + 1) if flags & 0x80 else 0) + i = skip_blocks(i + 1) # LZW minimum code size, then the data + elif block == 0x21: # extension + i = skip_blocks(i + 2) + else: + break + except IndexError: + pass + return frames + + +def _is_animated(data: bytes, mime_type: str) -> bool: + if mime_type == "image/gif": + return _gif_frames(data) > 1 + if mime_type == "image/png": + # An APNG declares its animation (acTL) before the first image data. + actl, idat = data.find(b"acTL"), data.find(b"IDAT") + return actl != -1 and (idat == -1 or actl < idat) + return False + + +def _crop_hint(width: int, height: int) -> str: + if width / height > _IMAGE_RATIO: + return f"{round(height * _IMAGE_RATIO)}x{height}" + return f"{width}x{round(width / _IMAGE_RATIO)}" + + +def _image_problems(label: str, data: bytes, mime_type: str, width: int, height: int) -> list[str]: + """Why Microsoft would refuse this image for an image extension (empty when it fits).""" + problems = [] + if mime_type not in _IMAGE_FORMATS: + problems.append(f"{label}: {mime_type} is not accepted; use JPEG, PNG or GIF.") + elif _is_animated(data, mime_type): + problems.append(f"{label}: animated images are not accepted; use a still image.") + if len(data) > _IMAGE_MAX_BYTES: + problems.append(f"{label}: {len(data) / 1024 / 1024:.1f} MB is over Microsoft's 5 MB limit.") + if width < _IMAGE_MIN_SIZE[0] or height < _IMAGE_MIN_SIZE[1]: + problems.append(f"{label}: {width}x{height} is smaller than Microsoft's minimum of 703x368 for image extensions.") + if width > _IMAGE_MAX_SIZE[0] or height > _IMAGE_MAX_SIZE[1]: + problems.append(f"{label}: {width}x{height} is larger than Microsoft's maximum (width 2592, height 2048); " + "scale it down, e.g. to 1200x628.") + ratio = width / height if height else 0 + if abs(ratio - _IMAGE_RATIO) > _IMAGE_RATIO * _IMAGE_RATIO_TOLERANCE: + problems.append(f"{label}: the aspect ratio is {ratio:.2f}:1; image extensions need 1.91:1 (e.g. 1200x628). " + f"Crop it to {_crop_hint(width, height)} first.") + return problems + + +def _image_label(payload: dict) -> str: + return str(payload.get("url") or payload.get("path") or f"upload {payload.get('upload_id')}") + + +def _draft_images(paths: list[str], urls: list[str], uploads: list[str]) -> tuple[list[dict], list[str]]: + """Load, validate and pin (sha256) every image; the bytes stay out of the plan. + + Loading reuses the Google Ads image tools: image_payloads checks the files + and fetches URLs through the private-address-proof fetcher, and + load_image_bytes reads the approved bytes back. + """ + from adloop.ads.write import image_payloads, load_image_bytes + + payloads, errors = image_payloads(paths, urls, uploads) + images, seen = [], set() + for payload in payloads: + label = _image_label(payload) + try: + data, _name = load_image_bytes(payload) + except Exception as exc: # noqa: BLE001 - a fetch or upload problem is the user's to fix + errors.append(f"{label}: {exc}") + continue + digest = hashlib.sha256(data).hexdigest() + if payload.get("sha256") and payload["sha256"] != digest: + errors.append(f"{label}: the image changed while it was being read; try again.") + continue + if digest in seen: + errors.append(f"{label}: the same image is in this draft twice.") + continue + seen.add(digest) + width, height = int(payload["width"]), int(payload["height"]) + errors.extend(_image_problems(label, data, str(payload["mime_type"]), width, height)) + images.append({**payload, "sha256": digest, "size_bytes": len(data), + "base64_chars": 4 * ((len(data) + 2) // 3)}) + return images, errors + + +def _approved_image(payload: dict) -> bytes: + """The previewed bytes of an image, re-read now; refuses one that changed or no longer fits.""" + from adloop.ads.write import load_image_bytes + + label = _image_label(payload) + data, _name = load_image_bytes(payload) + if hashlib.sha256(data).hexdigest() != payload["sha256"]: + raise ValueError(f"{label} changed since the preview; draft again.") + problems = _image_problems(label, data, str(payload["mime_type"]), int(payload["width"]), int(payload["height"])) + if problems: + raise ValueError("; ".join(problems)) + return data + + +def _describe_ms_image(payload: dict) -> str: + width, height = int(payload["width"]), int(payload["height"]) + return (f"{_image_label(payload)}: {_IMAGE_FORMATS.get(str(payload['mime_type']), payload['mime_type'])} " + f"{width}x{height} ({width / height:.2f}:1), {payload['size_bytes'] / 1024:.1f} KB") + + +def _linked_images(config, account, customer, association: str, entity_id: str) -> list[dict]: + return [a["AdExtension"] for a in _associated_extensions(config, account, customer, association, entity_id) + if a["AdExtension"].get("Type") == "ImageAdExtension"] + + +def draft_microsoft_image_extension( + config: AdLoopConfig, + *, + ad_account_id: str = "", + campaign_id: str = "", + ad_group_id: str = "", + scope: str = "", + image_paths: list[str] | None = None, + image_urls: list[str] | None = None, + upload_ids: list[str] | None = None, + alt_text: str = "", + display_text: str = "", + final_url: str = "", +) -> dict: + """Draft image extensions (one per image) for a campaign, an ad group or the account. + + Every image is loaded and checked now against Microsoft's limits; the + plan keeps its sha256, and the dry run and the apply read it again and + refuse one that changed. The apply uploads the images to the account's + media library (Media/Add), creates one ImageAdExtension per image and + links them (AdExtensionsAssociations/Set). + """ + from adloop.runtime import deployment_mode + + operation = "microsoft_add_image_extension" + blocked = _guard(operation, config) + if blocked: + return blocked + paths, urls, uploads = _clean(image_paths), _clean(image_urls), _clean(upload_ids) + if paths and deployment_mode() == "server": + return {"error": "image_paths can't be used here: local file paths aren't available on a hosted server; " + "pass image_urls or upload_ids instead."} + alt, display, url = (alt_text or "").strip(), (display_text or "").strip(), (final_url or "").strip() + errors: list[str] = [] + warnings: list[str] = [] + if not alt: + errors.append("alt_text is required: it describes the image for screen readers and shows on hover " + f"(at most {_ALT_TEXT_MAX} characters).") + elif len(alt) > _ALT_TEXT_MAX: + errors.append(f"alt_text is {len(alt)} characters; Microsoft allows {_ALT_TEXT_MAX}.") + if len(display) > _DISPLAY_TEXT_MAX: + errors.append(f"display_text is {len(display)} characters; Microsoft allows {_DISPLAY_TEXT_MAX}.") + count = len(paths) + len(urls) + len(uploads) + if not count: + errors.append("At least one image (image_paths, image_urls or upload_ids) is required.") + elif count > _IMAGES_PER_DRAFT: + errors.append(f"At most {_IMAGES_PER_DRAFT} images per draft (Microsoft uploads 10 per request); got {count}.") + if url: + _check_url(url, errors, warnings) + if errors: + return _validation_error(errors) + images, image_errors = _draft_images(paths, urls, uploads) + if image_errors: + return _validation_error(image_errors) + + _meta, account, customer = _ctx(config, ad_account_id) + target = _extension_target(config, account, customer, str(campaign_id or ""), (scope or "").strip().lower(), + ad_group_id=str(ad_group_id or "").strip()) + if isinstance(target, dict): + return target + association, entity_id, where = target + existing = _linked_images(config, account, customer, association, entity_id) + total = len(existing) + len(images) + if total > _IMAGE_LINKS_MAX: + return _validation_error([( + f"{where} has {len(existing)} image extension(s); {len(images)} more would make {total}, over " + f"Microsoft's {_IMAGE_LINKS_MAX} per account, campaign or ad group. Unlink some first " + "(remove_microsoft_entity, entity_type extension_association).")]) + if total > _IMAGE_LINKS_LOW: + warnings.append(f"{where} would have {total} image extensions. Microsoft's image extension reference " + f"lists {_IMAGE_LINKS_LOW} per entity while its help and bulk pages say " + f"{_IMAGE_LINKS_MAX}; if Microsoft refuses the link, the extensions stay in the " + "library unlinked.") + layouts = ["SearchSingle"] + (["SearchMultiple"] if display else []) + # [AUD]: "you can also extend search into native via image ad extensions". + warnings.append("Image extensions can take these search ads beyond Bing results: Microsoft's audience ads " + "guide says search ads are extended to native placements on the Microsoft Audience Network " + "(Outlook, MSN) using their image extensions. Check the ad groups' Audience Network setting " + "(get_microsoft_ad_groups) if they should stay on search.") + if display: + # [HELP]: at least five images and four image extensions; not with + # sitelink, enhanced sitelink, dynamic product, dynamic data or price cards. + warnings.append("display_text makes them eligible for the multi-image layout too. Microsoft shows that " + "layout only with at least five images across at least four image extensions, and not " + "next to sitelink, price, dynamic product or dynamic data extension cards.") + if any(p["mime_type"] == "image/png" for p in images): + warnings.append("Microsoft converts PNG images to JPEG; upload a JPEG if the quality matters.") + if existing: + warnings.append(f"{where} already has {len(existing)} image extension(s); Microsoft rotates them.") + shown: dict[str, Any] = {"images": [_describe_ms_image(p) for p in images], "alt_text": alt} + if display: + shown["display_text"] = display + shown["final_url"] = url or "the ad's own final URL" + shown["layouts"] = layouts + return _plan( + operation, _ASSOCIATION_ENTITY[association], entity_id, account, customer, + {"entity_name": where, **shown}, + {"association_type": association, "entity_id": entity_id, "image_payloads": images}, + warnings=warnings, + ) + + +def _image_extension(c: dict, media_id: str, payload: dict) -> dict: + """The ImageAdExtension for one uploaded image [EXT]; the image is its 1.91:1 LandscapeImageMedia asset.""" + ext: dict[str, Any] = { + "Type": "ImageAdExtension", + "AlternativeText": c["alt_text"], + "Description": str(payload.get("name") or "")[:_DESCRIPTION_MAX] or None, + "ImageMediaIds": [int(media_id)], + "Images": [{"Asset": {"Type": "ImageAsset", "Id": int(media_id), "SubType": "LandscapeImageMedia"}}], + "Layouts": list(c["layouts"]), + } + if c.get("display_text"): + ext["DisplayText"] = c["display_text"] + if c["final_url"].startswith(("http://", "https://")): + ext["FinalUrls"] = [c["final_url"]] + return {k: v for k, v in ext.items() if v is not None} + + +def _extension_row(assoc: dict, association: str, label: str, campaign_name: str | None) -> dict: + ext = assoc["AdExtension"] + kind = str(ext.get("Type") or "") + entity_id = str(assoc["EntityId"]) + row: dict[str, Any] = { + "level": _ASSOCIATION_ENTITY.get(association, association.lower()), "entity": label, "entity_id": entity_id, + "type": kind.replace("AdExtension", ""), "extension_id": str(ext.get("Id")), + "content": ext.get("Text") or ext.get("DisplayText") or ext.get("PhoneNumber") + or (f"{ext.get('Header')}: {', '.join(ext.get('Values') or [])}" if ext.get("Header") else None), + "final_urls": ext.get("FinalUrls"), + "editorial_status": assoc.get("EditorialStatus"), + "remove_id": f"{ext.get('Id')}~{entity_id}~{association}", + } + if association == "AdGroup": + row["campaign"] = campaign_name + if kind == "ImageAdExtension": + row.update(content=ext.get("AlternativeText"), alt_text=ext.get("AlternativeText"), + display_text=ext.get("DisplayText"), media_ids=_image_media_ids(ext), layouts=ext.get("Layouts"), + label=ext.get("Description"), source=ext.get("SourceType")) + return row + + +def _image_media_ids(ext: dict) -> list[str]: + """The media an image extension shows: its ImageMediaIds, or the assets of its Images links.""" + media = [str(i) for i in ext.get("ImageMediaIds") or [] if i is not None] or [ + str(link["Asset"]["Id"]) for link in ext.get("Images") or [] + if isinstance(link, dict) and isinstance(link.get("Asset"), dict) and link["Asset"].get("Id") is not None] + return sorted(set(media), key=lambda m: (len(m), m)) + + +# The association query returns image extensions without their Images, +# DisplayText and Layouts; those come only from GetAdExtensionsByIds when +# ReturnAdditionalFields asks for them (an unknown field name fails the whole +# request). Media metadata then gives each image's size and a viewable URL. +_IMAGE_EXTRA_FIELDS = "Images,DisplayText,Layouts" + + +def _image_details(config: AdLoopConfig, account: str, customer: str, rows: list[dict]) -> list[str]: + """Fill image rows with their media, display text, layouts and image links; insights on failure.""" + image_rows = [r for r in rows if r["type"] == "Image"] + if not image_rows: + return [] + try: + extensions: dict[str, dict] = {} + for chunk in _chunks(sorted({r["extension_id"] for r in image_rows})): + payload = campaign_request( + config, "AdExtensions/QueryByIds", + {"AccountId": account, "AdExtensionIds": [int(i) for i in chunk], + "AdExtensionType": "ImageAdExtension", "ReturnAdditionalFields": _IMAGE_EXTRA_FIELDS}, + account_id=account, customer_id=customer, + ) + extensions.update({str(e.get("Id")): e for e in payload.get("AdExtensions") or [] if isinstance(e, dict)}) + for row in image_rows: + ext = extensions.get(row["extension_id"]) + if ext: + row.update(media_ids=_image_media_ids(ext) or row["media_ids"], + display_text=ext.get("DisplayText") or row["display_text"], + layouts=ext.get("Layouts") or row["layouts"]) + media: dict[str, dict] = {} + for chunk in _chunks(sorted({m for r in image_rows for m in r["media_ids"]})): + payload = campaign_request(config, "MediaMetaData/QueryByIds", + {"AccountId": account, "MediaIds": [int(m) for m in chunk]}, + account_id=account, customer_id=customer) + for item in payload.get("MediaMetaData") or []: + if not isinstance(item, dict): + continue + reps = [r for r in item.get("Representations") or [] if isinstance(r, dict)] + best = max(reps, key=lambda r: (r.get("Width") or 0) * (r.get("Height") or 0), default={}) + media[str(item.get("Id"))] = {"media_id": str(item.get("Id")), "media_type": item.get("MediaType"), + "width": best.get("Width"), "height": best.get("Height"), + "url": best.get("Url")} + except MicrosoftAdsApiError as exc: + return [f"Image details could not be read, so image rows lack their images and display text: {exc}"] + for row in image_rows: + row["images"] = [media.get(m) or {"media_id": m} for m in row["media_ids"]] + return [] + + +def get_microsoft_ad_extensions(config: AdLoopConfig, *, ad_account_id: str = "", campaign_id: str = "") -> dict: + """Sitelinks, callouts, snippets, call and image extensions on ad groups, campaigns and the account.""" + meta, account, customer = _ctx(config, ad_account_id) + campaigns = [c for c in _campaigns(config, account, customer) if not campaign_id or str(c.get("Id")) == str(campaign_id)] + rows = [] + targets = [("Campaign", str(c.get("Id")), c.get("Name")) for c in campaigns] + if not campaign_id: + targets.append(("Account", account, "account")) + for association, entity_id, label in targets: + for a in _associated_extensions(config, account, customer, association, entity_id): + rows.append(_extension_row(a, association, label, None)) + # Ad group links (image extensions often live there), up to 100 ad groups a request. + groups = {str(g.get("Id")): (g, c) for c in campaigns for g in _ad_groups(config, account, customer, str(c.get("Id"))) + if g.get("Status") != "Deleted"} + for chunk in _chunks(list(groups)): + for a in _associated_extensions(config, account, customer, "AdGroup", chunk): + group, campaign = groups.get(a["EntityId"], ({}, {})) + rows.append(_extension_row(a, "AdGroup", group.get("Name") or a["EntityId"], campaign.get("Name"))) + insights = _image_details(config, account, customer, rows) + for c in campaigns: + mine = [r for r in rows if r["level"] == "campaign" and r["entity_id"] == str(c.get("Id"))] + if not any(r["type"] == "Sitelink" for r in mine): + insights.append(f"Campaign '{c.get('Name')}' has no sitelinks of its own.") + rejected = [r for r in rows if r["editorial_status"] in ("Disapproved", "Inactive")] + if rejected: + insights.append(f"{len(rejected)} extension(s) are disapproved or inactive.") + if not any(r["type"] == "Image" for r in rows): + insights.append("No image extensions are linked. Microsoft may add autogenerated ones to ad groups " + "without any; draft_microsoft_image_extension adds your own.") + return {"ad_account_id": account, "extensions": rows, "total": len(rows), "insights": insights} + + +def _apply_image_extensions(config: AdLoopConfig, c: dict, progress: _Progress) -> dict: + """Media/Add, then one ImageAdExtension per image, then the links; a later failure names what exists.""" + from adloop.safety.outcomes import PartialApplyError + + account = c["ad_account_id"] + payloads = c["image_payloads"] + # Every image is read and checked before anything is sent. + data = [_approved_image(p) for p in payloads] + # REST v13 AddMedia is POST .../CampaignManagement/v13/Media [ADD]; GenericImage + # is the MediaType Microsoft recommends for image extension media [IMG]. + media = [{"Type": "Image", "MediaType": "GenericImage", "Data": base64.b64encode(d).decode("ascii")} for d in data] + payload = _call(config, c, "POST", "Media", {"AccountId": account, "Media": media}, "image upload") + media_ids = [str(i) for i in payload.get("MediaIds") or [] if i is not None] + if len(media_ids) != len(media): + raise PartialApplyError( + f"Microsoft stored {len(media_ids)} of {len(media)} images (media ids {media_ids}) without saying why; " + "check the account's image library before drafting again.", + created={"media_ids": media_ids}, + ) + progress.created["media_ids"] = media_ids + progress.done.append(f"uploaded {len(media_ids)} image(s) to the media library (media ids {', '.join(media_ids)})") + + extensions = [_image_extension(c, mid, p) for mid, p in zip(media_ids, payloads, strict=True)] + payload = progress.step("Creating the image extensions", lambda: _call( + config, c, "POST", "AdExtensions", {"AccountId": account, "AdExtensions": extensions}, "image extensions")) + ids = [str((i or {}).get("Id")) for i in payload.get("AdExtensionIdentities") or [] if i and i.get("Id")] + progress.created["extension_ids"] = ids + progress.done.append(f"created image extension(s) {', '.join(ids)}") + progress.step("Linking the image extensions", lambda: _call(config, c, "POST", "AdExtensionsAssociations/Set", { + "AccountId": account, "AssociationType": c["association_type"], + "AdExtensionIdToEntityIdAssociations": [{"AdExtensionId": int(i), "EntityId": int(c["entity_id"])} for i in ids], + }, "image extension links")) + return {"media_ids": media_ids, "extension_ids": ids, "linked_to": c["entity_name"], "layouts": c["layouts"], + "next": "The images go through Microsoft's editorial review; get_microsoft_ad_extensions shows each " + "extension's editorial_status."} + + +def _check_extensions(s: Step) -> None: + config, c, account, customer, op = s.config, s.c, s.account, s.customer, s.plan.operation + if c["association_type"] == "Campaign": + s.entity("campaign", c["entity_id"]) + linked = _associated_extensions(config, account, customer, c["association_type"], c["entity_id"]) + if op == "microsoft_add_call_extension" and any(a["AdExtension"].get("Type") == "CallAdExtension" for a in linked): + raise ValueError("The campaign got a call extension since the draft.") + def key(ext): # noqa: E306 + return json.dumps({k: ext.get(k) for k in ("Type", "Text", "DisplayText", "Header", "Values", "PhoneNumber")}, + sort_keys=True).lower() + now = {key(a["AdExtension"]) for a in linked} + again = [e for e in c["extensions"] if key(e) in now] + if again: + raise ValueError(f"{len(again)} of these extensions are linked now (an earlier attempt may have added them).") + if op == "microsoft_add_sitelinks": + errors = [] + for ext in c["extensions"]: + _check_url(ext["FinalUrls"][0], errors, []) + if errors: + raise ValueError("; ".join(errors)) + + +def _apply_extensions(s: Step, progress: _Progress) -> dict: + config, c, account = s.config, s.c, s.account + payload = _call(config, c, "POST", "AdExtensions", {"AccountId": account, "AdExtensions": c["extensions"]}, "extensions") + ids = [str((i or {}).get("Id")) for i in payload.get("AdExtensionIdentities") or [] if i] + progress.done.append(f"created extension(s) {ids}") + progress.step("Linking the extensions", lambda: _call(config, c, "POST", "AdExtensionsAssociations/Set", { + "AccountId": account, "AssociationType": c["association_type"], + "AdExtensionIdToEntityIdAssociations": [{"AdExtensionId": int(i), "EntityId": int(c["entity_id"])} for i in ids], + }, "extension links")) + return {"extension_ids": ids, "linked_to": c["entity_name"]} + + +def _check_add_image_extension(s: Step) -> None: + config, c, account, customer = s.config, s.c, s.account, s.customer + if c["association_type"] in ("Campaign", "AdGroup"): + s.entity(_ASSOCIATION_ENTITY[c["association_type"]], c["entity_id"]) + images = c["image_payloads"] + for payload in images: + _approved_image(payload) # re-reads (URLs re-fetched) and re-checks every image + linked = _linked_images(config, account, customer, c["association_type"], c["entity_id"]) + if len(linked) + len(images) > _IMAGE_LINKS_MAX: + raise ValueError(f"{c['entity_name']} now has {len(linked)} image extension(s); {len(images)} more would " + f"go over Microsoft's {_IMAGE_LINKS_MAX}.") + if c["final_url"].startswith(("http://", "https://")): + errors = [] + _check_url(c["final_url"], errors, []) + if errors: + raise ValueError("; ".join(errors)) + s.checks["images_verified"] = len(images) + + +def _apply_add_image_extension(s: Step, progress: _Progress) -> dict: + config, c = s.config, s.c + return _apply_image_extensions(config, c, progress) + + +HANDLERS = { + "microsoft_add_sitelinks": Handler(_check_extensions, _apply_extensions), + "microsoft_add_callouts": Handler(_check_extensions, _apply_extensions), + "microsoft_add_structured_snippet": Handler(_check_extensions, _apply_extensions), + "microsoft_add_call_extension": Handler(_check_extensions, _apply_extensions), + "microsoft_add_image_extension": Handler(_check_add_image_extension, _apply_add_image_extension), +} diff --git a/src/adloop/microsoft_ads/manage/negatives.py b/src/adloop/microsoft_ads/manage/negatives.py new file mode 100644 index 00000000..89ea8536 --- /dev/null +++ b/src/adloop/microsoft_ads/manage/negatives.py @@ -0,0 +1,390 @@ +"""Negative keywords: direct ones and shared negative keyword lists.""" + +from __future__ import annotations + +from typing import TYPE_CHECKING + +from adloop.microsoft_ads.client import campaign_request +from adloop.microsoft_ads.manage._common import ( + _LIST_TYPE, + _MAX_LISTS_PER_CAMPAIGN, + NEGATIVE_MATCH_TYPES, + Handler, + Step, + _call, + _chunks, + _clean, + _ctx, + _plan, + _Progress, +) +from adloop.microsoft_ads.read import ( + _ad_groups, + _campaigns, + _keywords, +) +from adloop.microsoft_ads.write import _blocked as _guard +from adloop.microsoft_ads.write import ( + _validation_error, + find_entity, +) + +if TYPE_CHECKING: + from adloop.config import AdLoopConfig + + +def _negative_rows(keywords: list, match_type: str, errors: list[str]) -> list[dict]: + match = (match_type or "Phrase").strip().title() + if match not in NEGATIVE_MATCH_TYPES: + errors.append(f"match_type for negatives must be one of {list(NEGATIVE_MATCH_TYPES)}.") + rows, seen = [], set() + for text in _clean(keywords): + if len(text) > 100: + errors.append(f"Negative '{text[:20]}…' is longer than 100 characters.") + if text.lower() not in seen: + seen.add(text.lower()) + rows.append({"Text": text, "MatchType": match}) + if not rows and not errors: + errors.append("keywords needs at least one negative keyword.") + return rows + + +def _entity_negatives(config: AdLoopConfig, account: str, customer: str, entity_type: str, entity_id: str, + parent_id: str = "") -> list[dict]: + payload = campaign_request( + config, "NegativeKeywords/QueryByEntityIds", + {"EntityIds": [int(entity_id)], "EntityType": entity_type, "ParentEntityId": int(parent_id) if parent_id else None}, + account_id=account, customer_id=customer, + ) + out = [] + for entry in payload.get("EntityNegativeKeywords") or []: + out.extend(n for n in (entry or {}).get("NegativeKeywords") or [] if isinstance(n, dict)) + return out + + +def _shared_lists(config: AdLoopConfig, account: str, customer: str) -> list[dict]: + payload = campaign_request( + config, "SharedEntities/Query", {"SharedEntityType": _LIST_TYPE, "SharedEntityScope": "Account"}, + account_id=account, customer_id=customer, + ) + return [e for e in payload.get("SharedEntities") or [] if isinstance(e, dict)] + + +def _list_items(config: AdLoopConfig, account: str, customer: str, list_id: str) -> list[dict]: + payload = campaign_request( + config, "ListItems/QueryBySharedList", + {"SharedList": {"Type": _LIST_TYPE, "Id": int(list_id)}, "SharedEntityScope": "Account"}, + account_id=account, customer_id=customer, + ) + return [i for i in payload.get("ListItems") or [] if isinstance(i, dict)] + + +def _list_associations(config: AdLoopConfig, account: str, customer: str, campaign_ids: list[str]) -> list[dict]: + out = [] + for chunk in _chunks([int(c) for c in campaign_ids]): + payload = campaign_request( + config, "SharedEntityAssociations/QueryByEntityIds", + {"EntityIds": chunk, "EntityType": "Campaign", "SharedEntityType": _LIST_TYPE, "SharedEntityScope": "Account"}, + account_id=account, customer_id=customer, + ) + out.extend(a for a in payload.get("Associations") or [] if isinstance(a, dict)) + return out + + +def _positive_conflicts(config: AdLoopConfig, account: str, customer: str, campaign_ids: list[str], rows: list[dict]) -> list[str]: + texts = {r["Text"].lower(): r for r in rows} + hits = [] + for cid in campaign_ids: + for g in _ad_groups(config, account, customer, cid): + for k in _keywords(config, account, customer, str(g.get("Id"))): + text = str(k.get("Text") or "").lower() + if k.get("Status") == "Active" and text in texts: + hits.append(f"'{k.get('Text')}' ({g.get('Name')})") + return hits + + +def get_microsoft_negative_keywords(config: AdLoopConfig, *, ad_account_id: str = "", campaign_id: str = "") -> dict: + """Negative keywords of the account's campaigns: direct ones and shared lists with their items.""" + meta, account, customer = _ctx(config, ad_account_id) + campaigns = [c for c in _campaigns(config, account, customer) if not campaign_id or str(c.get("Id")) == str(campaign_id)] + direct = [] + for c in campaigns: + for n in _entity_negatives(config, account, customer, "Campaign", str(c.get("Id"))): + direct.append({"campaign_id": str(c.get("Id")), "campaign_name": c.get("Name"), "text": n.get("Text"), + "match_type": n.get("MatchType"), + "remove_id": f"Campaign~{c.get('Id')}~{n.get('Id')}"}) + lists = _shared_lists(config, account, customer) + associations = _list_associations(config, account, customer, [str(c.get("Id")) for c in campaigns]) if campaigns else [] + names = {str(c.get("Id")): c.get("Name") for c in campaigns} + attached: dict[str, list[str]] = {} + for a in associations: + attached.setdefault(str(a.get("SharedEntityId")), []).append(names.get(str(a.get("EntityId")), str(a.get("EntityId")))) + shared = [] + for lst in lists: + lid = str(lst.get("Id")) + if campaign_id and lid not in attached: + continue + items = _list_items(config, account, customer, lid) + shared.append({ + "list_id": lid, "name": lst.get("Name"), "item_count": lst.get("ItemCount", len(items)), + "attached_to": attached.get(lid, []), + "keywords": [{"text": i.get("Text"), "match_type": i.get("MatchType"), "remove_id": f"{lid}~{i.get('Id')}"} + for i in items], + }) + insights = [] + if direct: + insights.append(f"{len(direct)} negative(s) sit directly on campaigns; a shared list keeps them reusable across campaigns.") + unattached = [s["name"] for s in shared if not s["attached_to"]] + if unattached and not campaign_id: + insights.append(f"Lists attached to no campaign: {unattached}.") + return {"ad_account_id": account, "direct_negatives": direct, "negative_keyword_lists": shared, "insights": insights} + + +def add_microsoft_negative_keywords( + config: AdLoopConfig, *, ad_account_id: str = "", campaign_id: str = "", ad_group_id: str = "", + keywords: list | None = None, match_type: str = "Phrase", +) -> dict: + """Draft negatives directly on one campaign or ad group.""" + operation = "microsoft_add_negative_keywords" + blocked = _guard(operation, config) + if blocked: + return blocked + errors: list[str] = [] + if bool(campaign_id) == bool(ad_group_id): + errors.append("Pass exactly one of campaign_id or ad_group_id.") + rows = _negative_rows(keywords or [], match_type, errors) + if errors: + return _validation_error(errors) + meta, account, customer = _ctx(config, ad_account_id) + kind = "campaign" if campaign_id else "ad_group" + found = find_entity(config, account, customer, kind, str(campaign_id or ad_group_id)) + if not found: + return {"error": f"Microsoft {kind.replace('_', ' ')} '{campaign_id or ad_group_id}' was not found."} + entity, campaign = found["entity"], found["campaign"] + entity_type = "Campaign" if kind == "campaign" else "AdGroup" + existing = {(str(n.get("Text")).lower(), n.get("MatchType")) for n in _entity_negatives( + config, account, customer, entity_type, str(entity.get("Id")), "" if kind == "campaign" else str(campaign.get("Id")))} + new_rows = [r for r in rows if (r["Text"].lower(), r["MatchType"]) not in existing] + if not new_rows: + return {"error": "Every negative is already there."} + warnings = ["A shared negative keyword list (propose_microsoft_negative_keyword_list) keeps negatives reusable across campaigns."] + conflicts = _positive_conflicts(config, account, customer, [str(campaign.get("Id"))], new_rows) + if conflicts: + warnings.append(f"These negatives block active keywords: {conflicts[:10]}.") + return _plan( + operation, kind, str(entity.get("Id")), account, customer, + {"entity_name": entity.get("Name"), + "campaign_name": campaign.get("Name") if kind == "ad_group" else None, + "negatives": [f"{r['Text']} [{r['MatchType']}]" for r in new_rows]}, + {"entity_kind": entity_type, "campaign_id": str(campaign.get("Id")), "negative_rows": new_rows}, + warnings=warnings, + ) + + +def propose_microsoft_negative_keyword_list( + config: AdLoopConfig, *, ad_account_id: str = "", list_name: str = "", keywords: list | None = None, + match_type: str = "Phrase", campaign_ids: list[str] | None = None, +) -> dict: + """Draft a new shared negative keyword list and attach it to campaigns.""" + operation = "microsoft_create_negative_list" + blocked = _guard(operation, config) + if blocked: + return blocked + errors: list[str] = [] + list_name = (list_name or "").strip() + if not list_name or len(list_name) > 255: + errors.append("list_name is required (at most 255 characters).") + rows = _negative_rows(keywords or [], match_type, errors) + if len(rows) > 5000: + errors.append("At most 5,000 negatives in one draft.") + cids = _clean(campaign_ids) + if errors: + return _validation_error(errors) + meta, account, customer = _ctx(config, ad_account_id) + if list_name.lower() in {str(lst.get("Name")).lower() for lst in _shared_lists(config, account, customer)}: + return _validation_error([f"A negative keyword list named '{list_name}' already exists; add_to_microsoft_negative_keyword_list appends to it."]) + campaigns = {str(c.get("Id")): c for c in _campaigns(config, account, customer)} + unknown = [c for c in cids if c not in campaigns] + if unknown: + return _validation_error([f"Campaign(s) {unknown} are not in account {account}."]) + warnings = [] + if cids: + counts: dict[str, int] = {} + for a in _list_associations(config, account, customer, cids): + counts[str(a.get("EntityId"))] = counts.get(str(a.get("EntityId")), 0) + 1 + full = [campaigns[c].get("Name") for c in cids if counts.get(c, 0) >= _MAX_LISTS_PER_CAMPAIGN] + if full: + return _validation_error([f"Campaign(s) {full} already have {_MAX_LISTS_PER_CAMPAIGN} lists, Microsoft's limit."]) + conflicts = _positive_conflicts(config, account, customer, cids, rows) + if conflicts: + warnings.append(f"These negatives block active keywords: {conflicts[:10]}.") + else: + warnings.append("The list is attached to no campaign, so it blocks nothing until attached.") + return _plan( + operation, "negative_keyword_list", "", account, customer, + {"entity_name": list_name, "negatives": [f"{r['Text']} [{r['MatchType']}]" for r in rows], + "attach_to": [campaigns[c].get("Name") for c in cids]}, + {"campaign_ids": cids, "negative_rows": rows}, + warnings=warnings, + ) + + +def add_to_microsoft_negative_keyword_list( + config: AdLoopConfig, *, ad_account_id: str = "", list_id: str = "", keywords: list | None = None, + match_type: str = "Phrase", +) -> dict: + """Draft appending negatives to an existing shared list (items already there are skipped).""" + operation = "microsoft_add_to_negative_list" + blocked = _guard(operation, config) + if blocked: + return blocked + errors: list[str] = [] + rows = _negative_rows(keywords or [], match_type, errors) + if errors: + return _validation_error(errors) + meta, account, customer = _ctx(config, ad_account_id) + lists = {str(lst.get("Id")): lst for lst in _shared_lists(config, account, customer)} + if str(list_id) not in lists: + return {"error": f"Negative keyword list '{list_id}' was not found (get_microsoft_negative_keywords lists them)."} + items = _list_items(config, account, customer, str(list_id)) + have = {(str(i.get("Text")).lower(), i.get("MatchType")) for i in items} + new_rows = [r for r in rows if (r["Text"].lower(), r["MatchType"]) not in have] + if not new_rows: + return {"error": "Every negative is already in the list."} + attached = [str(a.get("EntityId")) for a in _list_associations( + config, account, customer, [str(c.get("Id")) for c in _campaigns(config, account, customer)]) + if str(a.get("SharedEntityId")) == str(list_id)] + warnings = [] + conflicts = _positive_conflicts(config, account, customer, attached, new_rows) + if conflicts: + warnings.append(f"These negatives block active keywords: {conflicts[:10]}.") + return _plan( + operation, "negative_keyword_list", str(list_id), account, customer, + {"entity_name": lists[str(list_id)].get("Name"), "attached_campaigns": len(attached), + "negatives": [f"{r['Text']} [{r['MatchType']}]" for r in new_rows]}, + {"negative_rows": new_rows}, + warnings=warnings, + ) + + +def _draft_list_link(config, *, attach: bool, ad_account_id: str, list_id: str, campaign_ids: list | None) -> dict: + operation = "microsoft_attach_negative_list" if attach else "microsoft_detach_negative_list" + blocked = _guard(operation, config) + if blocked: + return blocked + cids = _clean(campaign_ids) + if not cids: + return _validation_error(["campaign_ids needs at least one campaign id."]) + meta, account, customer = _ctx(config, ad_account_id) + lists = {str(lst.get("Id")): lst for lst in _shared_lists(config, account, customer)} + if str(list_id) not in lists: + return {"error": f"Negative keyword list '{list_id}' was not found."} + campaigns = {str(c.get("Id")): c for c in _campaigns(config, account, customer)} + unknown = [c for c in cids if c not in campaigns] + if unknown: + return _validation_error([f"Campaign(s) {unknown} are not in account {account}."]) + linked = {str(a.get("EntityId")) for a in _list_associations(config, account, customer, cids) + if str(a.get("SharedEntityId")) == str(list_id)} + targets = [c for c in cids if (c not in linked) == attach] + if not targets: + return {"error": "Nothing to change: every campaign is already " + ("attached." if attach else "detached.")} + warnings = [] + if not attach: + warnings.append("Detached campaigns stop blocking these negatives; the list itself stays.") + return _plan( + operation, "negative_keyword_list", str(list_id), account, customer, + {"entity_name": lists[str(list_id)].get("Name"), "campaigns": [campaigns[c].get("Name") for c in targets]}, + {"campaign_ids": targets}, + warnings=warnings, + ) + + +def attach_microsoft_negative_keyword_list(config, *, ad_account_id="", list_id="", campaign_ids=None) -> dict: + return _draft_list_link(config, attach=True, ad_account_id=ad_account_id, list_id=list_id, campaign_ids=campaign_ids) + + +def detach_microsoft_negative_keyword_list(config, *, ad_account_id="", list_id="", campaign_ids=None) -> dict: + return _draft_list_link(config, attach=False, ad_account_id=ad_account_id, list_id=list_id, campaign_ids=campaign_ids) + + +def _check_add_negative_keywords(s: Step) -> None: + config, plan, c, account, customer = s.config, s.plan, s.c, s.account, s.customer + found = s.entity(plan.entity_type, plan.entity_id) + have = {(str(n.get("Text")).lower(), n.get("MatchType")) for n in _entity_negatives( + config, account, customer, c["entity_kind"], plan.entity_id, + "" if plan.entity_type == "campaign" else str(found["campaign"].get("Id")))} + again = [r["Text"] for r in c["negative_rows"] if (r["Text"].lower(), r["MatchType"]) in have] + if again: + raise ValueError(f"Negative(s) {again} are there now (an earlier attempt may have added them).") + + +def _apply_add_negative_keywords(s: Step, progress: _Progress) -> dict: + config, plan, c = s.config, s.plan, s.c + _call(config, c, "POST", "EntityNegativeKeywords", {"EntityNegativeKeywords": [ + {"EntityId": int(plan.entity_id), "EntityType": c["entity_kind"], "NegativeKeywords": c["negative_rows"]}]}, + "negative keywords") + return {"entity": c["entity_name"], "negatives_added": len(c["negative_rows"])} + + +def _check_create_negative_list(s: Step) -> None: + config, c, account, customer = s.config, s.c, s.account, s.customer + if c["entity_name"].lower() in {str(x.get("Name")).lower() for x in _shared_lists(config, account, customer)}: + raise ValueError(f"A list named '{c['entity_name']}' now exists (an earlier attempt may have created it).") + + +def _apply_create_negative_list(s: Step, progress: _Progress) -> dict: + config, c = s.config, s.c + items = [{"Type": "NegativeKeyword", **r} for r in c["negative_rows"]] + payload = _call(config, c, "POST", "SharedEntity", {"SharedEntity": {"Type": _LIST_TYPE, "Name": c["entity_name"]}, + "ListItems": items[:5000], "SharedEntityScope": "Account"}, + "negative keyword list") + list_id = str(payload.get("SharedEntityId")) + progress.done.append(f"created list {list_id} with {len(items)} negatives") + if c["campaign_ids"]: + progress.step("Attaching the list", lambda: _call(config, c, "POST", "SharedEntityAssociations/Set", { + "Associations": [{"EntityId": int(cid), "EntityType": "Campaign", "SharedEntityId": int(list_id), + "SharedEntityType": _LIST_TYPE} for cid in c["campaign_ids"]], + "SharedEntityScope": "Account"}, "list attachment")) + return {"list_id": list_id, "name": c["entity_name"], "negatives": len(items), "attached_to": c["attach_to"]} + + +def _check_negative_list(s: Step) -> None: + config, plan, c, account, customer, op = s.config, s.plan, s.c, s.account, s.customer, s.plan.operation + if plan.entity_id not in {str(x.get("Id")) for x in _shared_lists(config, account, customer)}: + raise ValueError(f"Negative keyword list {plan.entity_id} no longer exists.") + if op == "microsoft_add_to_negative_list": + have = {(str(i.get("Text")).lower(), i.get("MatchType")) for i in _list_items(config, account, customer, plan.entity_id)} + again = [r["Text"] for r in c["negative_rows"] if (r["Text"].lower(), r["MatchType"]) in have] + if again: + raise ValueError(f"Negative(s) {again} are in the list now (an earlier attempt may have added them).") + + +def _apply_add_to_negative_list(s: Step, progress: _Progress) -> dict: + config, plan, c = s.config, s.plan, s.c + items = [{"Type": "NegativeKeyword", **r} for r in c["negative_rows"]] + for chunk in _chunks(items, 5000): + progress.step("Adding to the list", lambda chunk=chunk: _call(config, c, "POST", "ListItems", { + "ListItems": chunk, "SharedList": {"Type": _LIST_TYPE, "Id": int(plan.entity_id)}, + "SharedEntityScope": "Account"}, "list items")) + return {"list_id": plan.entity_id, "negatives_added": len(items)} + + +def _apply_list_link(s: Step, progress: _Progress) -> dict: + config, plan, c, op = s.config, s.plan, s.c, s.plan.operation + body = {"Associations": [{"EntityId": int(cid), "EntityType": "Campaign", "SharedEntityId": int(plan.entity_id), + "SharedEntityType": _LIST_TYPE} for cid in c["campaign_ids"]], + "SharedEntityScope": "Account"} + if op == "microsoft_attach_negative_list": + _call(config, c, "POST", "SharedEntityAssociations/Set", body, "list attachment") + else: + _call(config, c, "DELETE", "SharedEntityAssociations", body, "list detachment") + return {"list_id": plan.entity_id, "campaigns": c["campaigns"]} + + +HANDLERS = { + "microsoft_add_negative_keywords": Handler(_check_add_negative_keywords, _apply_add_negative_keywords), + "microsoft_create_negative_list": Handler(_check_create_negative_list, _apply_create_negative_list), + "microsoft_add_to_negative_list": Handler(_check_negative_list, _apply_add_to_negative_list), + "microsoft_attach_negative_list": Handler(_check_negative_list, _apply_list_link), + "microsoft_detach_negative_list": Handler(_check_negative_list, _apply_list_link), +} diff --git a/src/adloop/microsoft_ads/manage/removal.py b/src/adloop/microsoft_ads/manage/removal.py new file mode 100644 index 00000000..5c08bb2d --- /dev/null +++ b/src/adloop/microsoft_ads/manage/removal.py @@ -0,0 +1,196 @@ +"""Deleting entities, negatives, criteria and extension links.""" + +from __future__ import annotations + +from typing import TYPE_CHECKING, Any + +from adloop.microsoft_ads.manage._common import ( + _LIST_TYPE, + Handler, + Step, + _call, + _ctx, + _plan, + _Progress, +) +from adloop.microsoft_ads.manage.extensions import _ASSOCIATION_ENTITY +from adloop.microsoft_ads.manage.targeting import _block_label +from adloop.microsoft_ads.read import ( + is_negative, + target_criterions, +) +from adloop.microsoft_ads.write import _blocked as _guard +from adloop.microsoft_ads.write import ( + _validation_error, + find_entity, +) + +if TYPE_CHECKING: + from adloop.config import AdLoopConfig + +REMOVABLE = ("campaign", "ad_group", "ad", "keyword", "negative_keyword", "negative_list_item", + "campaign_criterion", "extension_association") + + +# Criterion types a campaign_criterion remove_id can point at, looked up in +# this order (one query each, until the criterion is found). +_CRITERION_KINDS = ("Location", "Radius", "DayTime", "LocationIntent", "Age", "Gender", "Device") + + +def _find_criterion(by_kind: dict[str, list[dict]], criterion_id: str) -> dict | None: + """The criterion with this id among a campaign's target criteria, with the others of its kind.""" + for kind, rows in by_kind.items(): + for row in rows: + if str(row.get("Id")) == str(criterion_id): + return {"criterion": row, "kind": kind, "siblings": rows} + return None + + +def _criterion_label(row: dict, kind: str) -> str: + crit = row.get("Criterion") or {} + side = "excluded" if is_negative(row) else "targeted" + if kind == "Location": + return f"location {crit.get('DisplayName') or crit.get('LocationId')} ({side})" + if kind == "Radius": + return f"radius {crit.get('Name') or ''} {crit.get('Radius')} {crit.get('RadiusUnit') or ''} ({side})".replace(" ", " ") + if kind == "DayTime": + return f"ad schedule window {_block_label(crit)}" + if kind == "LocationIntent": + return f"location intent {crit.get('IntentOption')}" + return f"{kind.lower()} criterion {row.get('Id')}" + + +def _positive_locations(rows: list[dict]) -> list[dict]: + return [r for r in rows if not is_negative(r)] + + +def _criterion_refusal(campaign_name: str, found: dict, by_kind: dict[str, list[dict]]) -> str | None: + """Why removing this criterion must go through update_microsoft_campaign_targeting, or None.""" + if found["kind"] not in ("Location", "Radius") or is_negative(found["criterion"]): + return None + positives = _positive_locations(by_kind.get("Location", []) + by_kind.get("Radius", [])) + others = [r for r in positives if str(r.get("Id")) != str(found["criterion"].get("Id"))] + if others: + return None + return (f"This is the last targeted location of campaign '{campaign_name}': without it the campaign " + "serves everywhere. Use update_microsoft_campaign_targeting with the full location list instead.") + + +def remove_microsoft_entity(config: AdLoopConfig, *, ad_account_id: str = "", entity_type: str = "", entity_id: str = "") -> dict: + """Draft deleting an entity (irreversible; double confirmation).""" + operation = "microsoft_remove_entity" + blocked = _guard(operation, config) + if blocked: + return blocked + entity_type = (entity_type or "").strip().lower() + entity_id = str(entity_id or "").strip() + if entity_type not in REMOVABLE: + return _validation_error([f"entity_type must be one of {list(REMOVABLE)}."]) + if not entity_id: + return _validation_error(["entity_id is required."]) + meta, account, customer = _ctx(config, ad_account_id) + shown: dict[str, Any] = {} + payload: dict[str, Any] = {} + request: dict[str, Any] + warnings: list[str] = [] + if entity_type in ("campaign", "ad_group", "ad", "keyword"): + found = find_entity(config, account, customer, entity_type, entity_id) + if not found: + return {"error": f"Microsoft {entity_type.replace('_', ' ')} '{entity_id}' was not found."} + entity = found["entity"] + label = entity.get("Name") or entity.get("Text") or f"{entity.get('Type')} ad {entity_id}" + shown = {"name": label, "campaign_name": found["campaign"].get("Name") if entity_type != "campaign" else None, + "ad_group_name": (found.get("ad_group") or {}).get("Name") if entity_type in ("ad", "keyword") else None, + "current_status": entity.get("Status")} + payload = {"campaign_id": str(found["campaign"].get("Id")), + "ad_group_id": str((found.get("ad_group") or {}).get("Id") or "")} + if entity_type == "campaign": + request = {"path": "Campaigns", "body": {"AccountId": account, "CampaignIds": [entity_id]}} + elif entity_type == "ad_group": + request = {"path": "AdGroups", "body": {"CampaignId": str(found["campaign"].get("Id")), "AdGroupIds": [entity_id]}} + elif entity_type == "ad": + request = {"path": "Ads", "body": {"AdGroupId": str(found["ad_group"].get("Id")), "AdIds": [entity_id]}} + else: + request = {"path": "Keywords", "body": {"AdGroupId": str(found["ad_group"].get("Id")), "KeywordIds": [entity_id]}} + warnings.append("Deleting cannot be undone; pausing keeps the history and lets it come back.") + else: + parts = entity_id.split("~") + if entity_type == "negative_keyword" and len(parts) == 3 and parts[0] in ("Campaign", "AdGroup"): + kind, owner, neg = parts + request = {"path": "EntityNegativeKeywords", "body": {"EntityNegativeKeywords": [ + {"EntityId": int(owner), "EntityType": kind, "NegativeKeywords": [{"Id": int(neg)}]}]}} + shown = {"negative_keyword_id": neg, "on": f"{kind} {owner}"} + elif entity_type == "negative_list_item" and len(parts) == 2: + list_id, item = parts + request = {"path": "ListItems", "body": {"ListItemIds": [int(item)], "SharedList": {"Type": _LIST_TYPE, "Id": int(list_id)}, + "SharedEntityScope": "Account"}} + shown = {"list_id": list_id, "item_id": item} + elif entity_type == "campaign_criterion" and len(parts) == 2 and all(x.isdigit() for x in parts): + cid, crit = parts + campaign = find_entity(config, account, customer, "campaign", cid) + if not campaign: + return {"error": f"Microsoft campaign '{cid}' was not found in account {account}."} + name = campaign["entity"].get("Name") + by_kind = target_criterions(config, account, customer, cid, _CRITERION_KINDS) + found = _find_criterion(by_kind, crit) + if not found: + return {"error": f"Campaign '{name}' has no target criterion {crit} (get_microsoft_campaigns lists them)."} + refusal = _criterion_refusal(name, found, by_kind) + if refusal: + return _validation_error([refusal]) + label = _criterion_label(found["criterion"], found["kind"]) + shown = {"name": label, "campaign_name": name, "criterion_type": found["kind"]} + payload = {"campaign_id": cid, "criterion_kind": found["kind"]} + request = {"path": "CampaignCriterions", "body": {"CampaignCriterionIds": [int(crit)], "CampaignId": int(cid), + "CriterionType": "Targets"}} + if found["kind"] == "LocationIntent": + warnings.append("Without its location intent the campaign falls back to Microsoft's default, " + "which also reaches people outside the locations who search for them.") + if found["kind"] == "DayTime" and len(found["siblings"]) == 1: + warnings.append("This is the campaign's last ad schedule window: without it the campaign serves at all hours.") + elif entity_type == "extension_association" and len(parts) == 3 and parts[2] in _ASSOCIATION_ENTITY: + ext, owner, association = parts + request = {"path": "AdExtensionsAssociations", "body": {"AccountId": account, "AssociationType": association, + "AdExtensionIdToEntityIdAssociations": [ + {"AdExtensionId": int(ext), "EntityId": int(owner)}]}} + shown = {"extension_id": ext, "removed_from": f"{association} {owner}"} + warnings.append("This unlinks the extension only; the extension (and an image extension's images) " + "stays in the account's library.") + else: + return _validation_error([ + "entity_id format: negative_keyword 'Campaign~~' or 'AdGroup~~', " + "negative_list_item '~', campaign_criterion '~', " + "extension_association '~~' (the remove_id values the read " + "tools return)." + ]) + return _plan(operation, entity_type, entity_id, account, customer, + {"entity_name": shown.pop("name", None) or entity_id, **shown}, + {**payload, "request": request}, warnings=warnings, double=True) + + +def _check_remove_entity(s: Step) -> None: + config, plan, account, customer = s.config, s.plan, s.account, s.customer + if plan.entity_type in ("campaign", "ad_group", "ad", "keyword"): + s.entity(plan.entity_type, plan.entity_id) + elif plan.entity_type == "campaign_criterion": + cid, crit = plan.entity_id.split("~") + name = s.entity("campaign", cid)["entity"].get("Name") + by_kind = target_criterions(config, account, customer, cid, _CRITERION_KINDS) + found = _find_criterion(by_kind, crit) + if not found: + raise ValueError(f"Criterion {crit} is no longer on campaign '{name}'.") + refusal = _criterion_refusal(name, found, by_kind) + if refusal: + raise ValueError(refusal) + + +def _apply_remove_entity(s: Step, progress: _Progress) -> dict: + config, plan, c = s.config, s.plan, s.c + request = c["request"] + _call(config, c, "DELETE", request["path"], request["body"], f"{plan.entity_type.replace('_', ' ')} removal") + return {"removed": plan.entity_type, "entity_id": plan.entity_id} + + +HANDLERS = { + "microsoft_remove_entity": Handler(_check_remove_entity, _apply_remove_entity), +} diff --git a/src/adloop/microsoft_ads/manage/targeting.py b/src/adloop/microsoft_ads/manage/targeting.py new file mode 100644 index 00000000..444e7fa5 --- /dev/null +++ b/src/adloop/microsoft_ads/manage/targeting.py @@ -0,0 +1,332 @@ +"""Campaign targeting: included and excluded locations, location intent, ad schedule.""" + +from __future__ import annotations + +from typing import TYPE_CHECKING, Any + +from adloop.microsoft_ads.manage._common import ( + _MINUTES, + DAYS, + INTENTS, + Handler, + Step, + _call, + _chunks, + _clean, + _ctx, + _plan, + _Progress, + _same, +) +from adloop.microsoft_ads.read import ( + is_negative, + target_criterions, +) +from adloop.microsoft_ads.write import _blocked as _guard +from adloop.microsoft_ads.write import ( + _validation_error, + find_entity, +) + +if TYPE_CHECKING: + from adloop.config import AdLoopConfig + + +def _current_targeting(config: AdLoopConfig, account: str, customer: str, campaign_id: str) -> dict: + found = target_criterions(config, account, customer, campaign_id, ("Location", "LocationIntent", "DayTime")) + included = {} + excluded = {} + for c in found["Location"]: + crit = c.get("Criterion") or {} + entry = {"criterion_id": str(c.get("Id")), "name": crit.get("DisplayName") or str(crit.get("LocationId"))} + target = excluded if is_negative(c) else included + target[str(crit.get("LocationId"))] = entry + intent = found["LocationIntent"] + schedule = found["DayTime"] + return { + "included": included, + "excluded": excluded, + "intent": {"criterion_id": str(intent[0].get("Id")), + "option": (intent[0].get("Criterion") or {}).get("IntentOption")} if intent else None, + "schedule": [ + {"criterion_id": str(c.get("Id")), **{k: (c.get("Criterion") or {}).get(k) + for k in ("Day", "FromHour", "FromMinute", "ToHour", "ToMinute")}} + for c in schedule + ], + } + + +def _schedule_blocks(schedule: list, errors: list[str]) -> list[dict]: + blocks = [] + for i, raw in enumerate(schedule or []): + if not isinstance(raw, dict): + errors.append(f"ad_schedule[{i}] must be an object with day_of_week, start_hour, end_hour.") + continue + day = str(raw.get("day_of_week") or raw.get("day") or "").strip().title() + try: + start_h, end_h = int(raw.get("start_hour")), int(raw.get("end_hour")) + start_m, end_m = int(raw.get("start_minute") or 0), int(raw.get("end_minute") or 0) + except (TypeError, ValueError): + errors.append(f"ad_schedule[{i}] hours and minutes must be whole numbers.") + continue + if day not in DAYS: + errors.append(f"ad_schedule[{i}].day_of_week must be one of {list(DAYS)}, got '{raw.get('day_of_week') or raw.get('day')}'.") + if not (0 <= start_h <= 23 and 0 <= end_h <= 24) or (end_h == 24 and end_m): + errors.append(f"ad_schedule[{i}] hours are 0–23 to start and 0–24 to end (24 only with minute 0).") + if start_m not in _MINUTES or end_m not in _MINUTES: + errors.append(f"ad_schedule[{i}] minutes are 0, 15, 30 or 45.") + if (end_h, end_m) <= (start_h, start_m): + errors.append(f"ad_schedule[{i}] must end after it starts.") + blocks.append({"Day": day, "FromHour": start_h, "FromMinute": _MINUTES.get(start_m, "Zero"), + "ToHour": end_h, "ToMinute": _MINUTES.get(end_m, "Zero")}) + by_day: dict[str, list] = {} + for b in blocks: + by_day.setdefault(b["Day"], []).append(b) + for day, items in by_day.items(): + minutes = sorted((b["FromHour"] * 60 + list(_MINUTES.values()).index(b["FromMinute"]) * 15, + b["ToHour"] * 60 + list(_MINUTES.values()).index(b["ToMinute"]) * 15) for b in items) + if any(a[1] > b[0] for a, b in zip(minutes, minutes[1:])): + errors.append(f"ad_schedule windows on {day} overlap.") + if len(items) > _MAX_WINDOWS_PER_DAY: + errors.append(f"At most {_MAX_WINDOWS_PER_DAY} ad_schedule windows on {day} (Microsoft's limit).") + return blocks + + +# Microsoft: "the maximum number of day and time criteria per day that you +# can set is seven" (per campaign or ad group; DayTimeCriterion reference). +_MAX_WINDOWS_PER_DAY = 7 + + +def _block_span(b: dict) -> tuple[str, int, int]: + """(day, start minute, end minute) of a DayTime window.""" + rev = {v: k for k, v in _MINUTES.items()} + return (str(b.get("Day")), int(b.get("FromHour") or 0) * 60 + rev.get(b.get("FromMinute"), 0), + int(b.get("ToHour") or 0) * 60 + rev.get(b.get("ToMinute"), 0)) + + +def _schedule_steps(current: list[dict], blocks: list[dict], campaign_id: str) -> dict: + """Order a schedule replacement the way Microsoft allows it. + + A DayTime window cannot be edited, only deleted and added, and windows + in a campaign must not overlap. Unchanged windows stay; new windows that + overlap none of today's go in first; then the old ones are deleted; then + the remaining new ones are added. ``gap`` is True when, between the last + two steps, the campaign has no window at all (it then serves at all hours). + """ + old = {_block_span(c): c for c in current} + new = {_block_span(b): b for b in blocks} + keep = set(old) & set(new) + remove = [old[s]["criterion_id"] for s in old if s not in keep] + to_add = [new[s] for s in new if s not in keep] + + def overlaps(span: tuple[str, int, int]) -> bool: + return any(o[0] == span[0] and span[1] < o[2] and o[1] < span[2] for o in old if o not in keep) + + def item(b: dict) -> dict: + return {"Type": "BiddableCampaignCriterion", "CampaignId": campaign_id, + "Criterion": {"Type": "DayTimeCriterion", **b}, + "CriterionBid": {"Type": "BidMultiplier", "Multiplier": 0}} + + # Before the deletes, a day still holds all of today's windows, and + # Microsoft allows at most seven per day: add early only what fits. + room = {} + for span in old: + room[span[0]] = room.get(span[0], _MAX_WINDOWS_PER_DAY) - 1 + first, after = [], [] + for b in to_add: + span = _block_span(b) + if not overlaps(span) and room.get(span[0], _MAX_WINDOWS_PER_DAY) > 0: + room[span[0]] = room.get(span[0], _MAX_WINDOWS_PER_DAY) - 1 + first.append(item(b)) + else: + after.append(item(b)) + return {"schedule_add_first": first, "schedule_delete": remove, "schedule_add_after": after, + "schedule_kept": [_block_label(old[s]) for s in old if s in keep], + "gap": bool(after) and not keep and not first} + + +def _block_label(b: dict) -> str: + rev = {v: k for k, v in _MINUTES.items()} + return f"{b['Day'][:3]} {b['FromHour']:02d}:{rev.get(b['FromMinute'], 0):02d}–{b['ToHour']:02d}:{rev.get(b['ToMinute'], 0):02d}" + + +def update_microsoft_campaign_targeting( + config: AdLoopConfig, + *, + ad_account_id: str = "", + campaign_id: str = "", + location_ids: list[str] | None = None, + excluded_location_ids: list[str] | None = None, + location_intent: str = "", + ad_schedule: list[dict] | None = None, +) -> dict: + """Draft targeting changes: included and excluded locations, location intent, ad schedule.""" + operation = "microsoft_update_targeting" + blocked = _guard(operation, config) + if blocked: + return blocked + errors: list[str] = [] + campaign_id = str(campaign_id or "").strip() + if not campaign_id: + errors.append("campaign_id is required") + include = _clean(location_ids) if location_ids is not None else None + exclude = _clean(excluded_location_ids) if excluded_location_ids is not None else None + if include is not None and not include: + errors.append("An empty location list would let the campaign serve everywhere; pass at least one location id.") + if include and exclude and set(include) & set(exclude): + errors.append(f"Location(s) {sorted(set(include) & set(exclude))} cannot be both included and excluded.") + bad_ids = [i for i in (include or []) + (exclude or []) if not i.isdigit()] + if bad_ids: + errors.append(f"Location ids are numbers (search_microsoft_locations); got {bad_ids}.") + intent = (location_intent or "").strip() + if intent and intent not in INTENTS: + errors.append(f"location_intent must be one of {list(INTENTS)}.") + blocks = _schedule_blocks(ad_schedule, errors) if ad_schedule is not None else None + if errors: + return _validation_error(errors) + if include is None and exclude is None and not intent and blocks is None: + return {"error": "Nothing to change: pass location_ids, excluded_location_ids, location_intent or ad_schedule."} + meta, account, customer = _ctx(config, ad_account_id) + found = find_entity(config, account, customer, "campaign", campaign_id) + if not found: + return {"error": f"Microsoft campaign '{campaign_id}' was not found in account {account}."} + campaign = found["entity"] + current = _current_targeting(config, account, customer, campaign_id) + names: dict[str, str] = {} + try: + from adloop.microsoft_ads.read import _GEO_CACHE, location_names + + if _GEO_CACHE.get("rows"): + names = location_names(_GEO_CACHE["rows"], (include or []) + (exclude or [])) + except Exception: # noqa: BLE001 — names are a convenience + names = {} + label = lambda i: names.get(i) or current["included"].get(i, {}).get("name") or current["excluded"].get(i, {}).get("name") or f"id {i}" # noqa: E731 + plan_ops: dict[str, Any] = {"add": [], "delete": [], "update": [], + "schedule_add_first": [], "schedule_delete": [], "schedule_add_after": []} + shown: dict[str, Any] = {} + warnings: list[str] = [] + if include is not None: + add = [i for i in include if i not in current["included"]] + drop = [current["included"][i]["criterion_id"] for i in current["included"] if i not in include] + plan_ops["add"] += [{"Type": "BiddableCampaignCriterion", "CampaignId": campaign_id, + "Criterion": {"Type": "LocationCriterion", "LocationId": int(i)}, + "CriterionBid": {"Type": "BidMultiplier", "Multiplier": 0}} for i in add] + plan_ops["delete"] += drop + shown["locations"] = {"from": [v["name"] for v in current["included"].values()], + "to": [label(i) for i in include], "added": [label(i) for i in add], + "removed": [current["included"][i]["name"] for i in current["included"] if i not in include]} + if exclude is not None: + add = [i for i in exclude if i not in current["excluded"]] + drop = [current["excluded"][i]["criterion_id"] for i in current["excluded"] if i not in exclude] + plan_ops["add"] += [{"Type": "NegativeCampaignCriterion", "CampaignId": campaign_id, + "Criterion": {"Type": "LocationCriterion", "LocationId": int(i)}} for i in add] + plan_ops["delete"] += drop + shown["excluded_locations"] = {"from": [v["name"] for v in current["excluded"].values()], + "to": [label(i) for i in exclude]} + if intent and intent != (current["intent"] or {}).get("option"): + item = {"Type": "BiddableCampaignCriterion", "CampaignId": campaign_id, + "Criterion": {"Type": "LocationIntentCriterion", "IntentOption": intent}} + if current["intent"]: + plan_ops["update"].append({**item, "Id": current["intent"]["criterion_id"]}) + else: + plan_ops["add"].append(item) + shown["location_intent"] = {"from": (current["intent"] or {}).get("option") or "PeopleInOrSearchingForOrViewingPages (default)", + "to": intent} + if intent != "PeopleIn": + warnings.append("This intent also reaches people outside the locations who search for or about them.") + if blocks is not None: + steps = _schedule_steps(current["schedule"], blocks, campaign_id) + gap = steps.pop("gap") + plan_ops.update(steps) + # The campaign decides whose clock the hours follow. + searcher_time = bool(campaign.get("AdScheduleUseSearcherTimeZone")) + current["searcher_time_zone"] = searcher_time + zone = "each searcher's own time zone" if searcher_time else f"the account time zone ({meta['time_zone']})" + shown["ad_schedule"] = {"from": [_block_label(b) for b in current["schedule"]] or "all hours", + "to": [_block_label(b) for b in blocks] or "all hours", + "hours_in": zone} + if searcher_time: + warnings.append("This campaign runs its ad schedule in each searcher's own time zone " + "(AdScheduleUseSearcherTimeZone), not the account's: 09:00 means 09:00 where the searcher is.") + else: + warnings.append(f"Ad schedule hours are in the account time zone ({meta['time_zone']}), not the searcher's.") + if blocks and not current["schedule"]: + warnings.append("The campaign serves at all hours today; this schedule switches every other hour off.") + if gap: + warnings.append("Microsoft cannot edit a schedule window, only delete and add one, and windows may not " + "overlap: the old windows are removed before the new ones are added, so for a moment " + "the campaign has no schedule and serves at all hours. If adding the new windows then " + "fails, the apply reports it (PARTIAL_APPLY) and the campaign stays unscheduled until " + "the schedule is added again.") + if not any(v for k, v in plan_ops.items() if k != "schedule_kept"): + return {"error": "Nothing to change: the targeting already matches."} + return _plan( + operation, "campaign", campaign_id, account, customer, + {"entity_name": campaign.get("Name"), "changes": shown}, + {"operations": plan_ops, "before": current}, + warnings=warnings, + double=bool(blocks) and not current["schedule"], + ) + + +def _check_update_targeting(s: Step) -> None: + config, plan, c, account, customer = s.config, s.plan, s.c, s.account, s.customer + campaign = s.entity("campaign", plan.entity_id)["entity"] + now = _current_targeting(config, account, customer, plan.entity_id) + if "searcher_time_zone" in c["before"]: + now["searcher_time_zone"] = bool(campaign.get("AdScheduleUseSearcherTimeZone")) + if now["searcher_time_zone"] != c["before"]["searcher_time_zone"]: + raise ValueError("The campaign's ad schedule time zone setting (AdScheduleUseSearcherTimeZone) " + "changed since the draft, so the approved hours would mean other times; draft again.") + if not _same(now, c["before"]): + raise ValueError("The campaign's targeting changed since the draft; draft again.") + + +def _apply_update_targeting(s: Step, progress: _Progress) -> dict: + config, plan, c = s.config, s.plan, s.c + ops = c["operations"] + for chunk in _chunks(ops["add"]): + progress.step("Adding targeting", lambda chunk=chunk: _call( + config, c, "POST", "CampaignCriterions", {"CampaignCriterions": chunk, "CriterionType": "Targets"}, "targeting additions")) + progress.done.append(f"added {len(chunk)} criterion(s)") + for chunk in _chunks(ops["update"]): + progress.step("Updating location intent", lambda chunk=chunk: _call( + config, c, "PUT", "CampaignCriterions", {"CampaignCriterions": chunk, "CriterionType": "Targets"}, "location intent")) + progress.done.append("updated location intent") + for chunk in _chunks(ops["delete"]): + progress.step("Removing old targeting", lambda chunk=chunk: _call( + config, c, "DELETE", "CampaignCriterions", + {"CampaignCriterionIds": [int(x) for x in chunk], "CampaignId": int(plan.entity_id), "CriterionType": "Targets"}, + "targeting removal")) + progress.done.append(f"removed {len(chunk)} criterion(s)") + # Schedule windows: non-overlapping new ones, then the old ones out, + # then the rest (see _schedule_steps). + for chunk in _chunks(ops.get("schedule_add_first") or []): + progress.step("Adding new ad schedule windows", lambda chunk=chunk: _call( + config, c, "POST", "CampaignCriterions", {"CampaignCriterions": chunk, "CriterionType": "Targets"}, "ad schedule")) + progress.done.append(f"added {len(chunk)} schedule window(s)") + for chunk in _chunks(ops.get("schedule_delete") or []): + progress.step("Removing the old ad schedule windows", lambda chunk=chunk: _call( + config, c, "DELETE", "CampaignCriterions", + {"CampaignCriterionIds": [int(x) for x in chunk], "CampaignId": int(plan.entity_id), "CriterionType": "Targets"}, + "ad schedule removal")) + progress.done.append(f"removed {len(chunk)} schedule window(s)") + remaining = list(ops.get("schedule_kept") or []) + if ops.get("schedule_add_first"): + remaining.append(f"{len(ops['schedule_add_first'])} new window(s) added before the removal") + for chunk in _chunks(ops.get("schedule_add_after") or []): + progress.step( + "Adding the new ad schedule windows (the windows they replace are already removed; until this " + "succeeds the campaign keeps " + + (", ".join(remaining) if remaining else "no ad schedule and serves at all hours") + ")", + lambda chunk=chunk: _call(config, c, "POST", "CampaignCriterions", + {"CampaignCriterions": chunk, "CriterionType": "Targets"}, "ad schedule")) + progress.done.append(f"added {len(chunk)} schedule window(s)") + schedule_added = len(ops.get("schedule_add_first") or []) + len(ops.get("schedule_add_after") or []) + return {"campaign_id": plan.entity_id, "added": len(ops["add"]) + schedule_added, "updated": len(ops["update"]), + "removed": len(ops["delete"]) + len(ops.get("schedule_delete") or [])} + + +HANDLERS = { + "microsoft_update_targeting": Handler(_check_update_targeting, _apply_update_targeting), +} diff --git a/tests/test_microsoft_ads_manage.py b/tests/test_microsoft_ads_manage.py index f3301093..765aa8bb 100644 --- a/tests/test_microsoft_ads_manage.py +++ b/tests/test_microsoft_ads_manage.py @@ -1838,3 +1838,19 @@ def test_seven_schedule_windows_a_day_are_allowed(self, api, config): eight = seven + [{"day_of_week": "Monday", "start_hour": 20, "end_hour": 21}] assert "At most 7 ad_schedule windows on Monday" in _text( manage.update_microsoft_campaign_targeting(config, campaign_id=CAMPAIGN, ad_schedule=eight)) + + +class TestHandlerTable: + def test_every_operation_has_a_check_and_an_apply(self): + assert manage.OPERATIONS == frozenset(manage.HANDLERS) + for op, handler in manage.HANDLERS.items(): + assert op.startswith("microsoft_") and callable(handler.preflight) and callable(handler.apply) + + def test_an_unknown_operation_is_refused(self, config): + from adloop.safety.preview import ChangePlan + + plan = ChangePlan(operation="microsoft_unknown", apply_only_payload={"ad_account_id": ACCOUNT}) + with pytest.raises(ValueError, match="Unknown Microsoft operation"): + manage.preflight(config, plan) + with pytest.raises(ValueError, match="Unknown Microsoft operation"): + manage.apply_plan(config, plan) From 8fb66c1ff42279e3c0fbcae59aab9958e03ef92f Mon Sep 17 00:00:00 2001 From: Illia Sapryga Date: Sun, 8 Nov 2026 16:50:53 -0600 Subject: [PATCH 6/6] Microsoft Advertising: campaign reads ask for their criteria types in one query Found in the live run: CampaignCriterions/QueryByIds refuses the "Targets" shorthand (4503 CampaignCriterionTypeInvalid, "Invalid API Campaign Criterion Type : Targets on API tier"), which adds, updates and deletes accept. The types joined by commas ("Location,LocationIntent,Radius") are accepted, so get_microsoft_campaigns now makes one criterion call per campaign; the per-type fallback stays for a refusal. The test fakes refuse "Targets" in a query, as Microsoft does. --- src/adloop/microsoft_ads/read.py | 11 +++++++---- tests/test_microsoft_ads.py | 8 ++++---- tests/test_microsoft_ads_manage.py | 16 +++++++++------- 3 files changed, 20 insertions(+), 15 deletions(-) diff --git a/src/adloop/microsoft_ads/read.py b/src/adloop/microsoft_ads/read.py index 421bad0e..cf31176e 100644 --- a/src/adloop/microsoft_ads/read.py +++ b/src/adloop/microsoft_ads/read.py @@ -404,9 +404,12 @@ def is_negative(c: dict) -> bool: TARGET_KINDS = ("Location", "LocationIntent", "Radius", "DayTime") -# One "Targets" query returns every target criterion of a campaign instead of -# one call per type. If Microsoft ever refuses it, the per-type queries take -# over for the rest of the process. +# One query with the types joined by commas ("Location,LocationIntent,...") +# returns every target criterion of a campaign instead of one call per type. +# QueryByIds refuses the "Targets" shorthand that adds, updates and deletes +# accept (seen live: 4503 CampaignCriterionTypeInvalid, "Invalid API Campaign +# Criterion Type : Targets on API tier"). If Microsoft ever refuses the +# joined form, the per-type queries take over for the rest of the process. _targets_query = {"refused": False} @@ -415,7 +418,7 @@ def target_criterions(config: AdLoopConfig, account: str, customer: str, campaig """A campaign's target criteria by kind, in one call where Microsoft allows it.""" if not _targets_query["refused"]: try: - rows = _criterions(config, account, customer, campaign_id, "Targets") + rows = _criterions(config, account, customer, campaign_id, ",".join(kinds)) except MicrosoftAdsApiError as exc: if exc.status != 400: raise diff --git a/tests/test_microsoft_ads.py b/tests/test_microsoft_ads.py index 1d2be17d..a55f6224 100644 --- a/tests/test_microsoft_ads.py +++ b/tests/test_microsoft_ads.py @@ -198,10 +198,10 @@ def handle(config, service, path, body=None, *, method="POST", account_id="", cu if key == ("campaign", "Campaigns/QueryByAccountId"): return _CAMPAIGNS if key == ("campaign", "CampaignCriterions/QueryByIds"): - if body["CriterionType"] == "Targets": - return {"CampaignCriterions": [c for (cid, _kind), rows in _CRITERIONS.items() - if cid == body["CampaignId"] for c in rows]} - return {"CampaignCriterions": _CRITERIONS.get((body["CampaignId"], body["CriterionType"]), [])} + # Like Microsoft: several types joined by commas in one query. + kinds = body["CriterionType"].split(",") + return {"CampaignCriterions": [c for (cid, kind), rows in _CRITERIONS.items() + if cid == body["CampaignId"] and kind in kinds for c in rows]} if key == ("campaign", "AdGroups/QueryByCampaignId"): return {"AdGroups": _AD_GROUPS.get(body["CampaignId"], [])} if key == ("campaign", "Keywords/QueryByAdGroupId"): diff --git a/tests/test_microsoft_ads_manage.py b/tests/test_microsoft_ads_manage.py index 765aa8bb..737ec9d1 100644 --- a/tests/test_microsoft_ads_manage.py +++ b/tests/test_microsoft_ads_manage.py @@ -90,7 +90,8 @@ def __init__(self): self.in_store_pilot = True self.calls: list[dict] = [] self.fail: dict[tuple, Exception] = {} - # Whether Microsoft refuses one "Targets" query for every criterion type. + # Whether Microsoft refuses one query for several criterion types + # ("Location,LocationIntent,..."). It always refuses "Targets" there. self.refuse_targets_query = False self._next = 5000 @@ -140,11 +141,12 @@ def __call__(self, config, service, path, body=None, *, method="POST", account_i out.append(c) return {"Campaigns": out} if path == "CampaignCriterions/QueryByIds": - kind = body["CriterionType"] - if kind == "Targets" and self.refuse_targets_query: - raise MicrosoftAdsApiError("InvalidCriterionType", status=400, codes=["InvalidCriterionType"]) + kinds = body["CriterionType"].split(",") + if "Targets" in kinds or (len(kinds) > 1 and self.refuse_targets_query): + # Seen live: 4503 CampaignCriterionTypeInvalid for "Targets" in a query. + raise MicrosoftAdsApiError("CampaignCriterionTypeInvalid", status=400, codes=["4503"]) return {"CampaignCriterions": [copy.deepcopy(c) for c in self.criteria.get(str(body["CampaignId"]), []) - if kind == "Targets" or c["Criterion"]["Type"].replace("Criterion", "") == kind]} + if c["Criterion"]["Type"].replace("Criterion", "") in kinds]} if path == "AdGroups/QueryByCampaignId": return {"AdGroups": [self._pub(g) for g in self.ad_groups.values() if g["_campaign"] == str(body["CampaignId"])]} if path == "Keywords/QueryByAdGroupId": @@ -1793,14 +1795,14 @@ def test_a_keyword_removal_reads_only_its_own_ad_group_after_the_draft(self, api def test_campaign_reads_ask_once_per_campaign_for_its_targeting(self, api, config): read.get_microsoft_campaigns(config) queries = [c["body"] for c in api.calls if c["path"] == "CampaignCriterions/QueryByIds"] - assert [q["CriterionType"] for q in queries] == ["Targets"] * len(api.campaigns) + assert [q["CriterionType"] for q in queries] == ["Location,LocationIntent,Radius"] * len(api.campaigns) def test_a_refused_targets_query_falls_back_to_one_per_type(self, api, config): api.refuse_targets_query = True rows = {r["campaign_id"]: r for r in read.get_microsoft_campaigns(config)["campaigns"]} assert rows[CAMPAIGN]["locations"]["included"] == ["Springfield, Illinois"] kinds = [c["body"]["CriterionType"] for c in api.calls if c["path"] == "CampaignCriterions/QueryByIds"] - assert kinds.count("Targets") == 1 and kinds.count("Location") == len(api.campaigns) + assert kinds.count("Location,LocationIntent,Radius") == 1 and kinds.count("Location") == len(api.campaigns) class TestReviewReads: