@topy-ai/maggie 0.7.48 → 0.7.49

package/bundled-tools/runtime/google_remediation.py

@@ -0,0 +1,152 @@
+"""Map redacted Google provider failures to one prerequisite and one safe action.
+
+The classifier is deterministic and offline. It reads an error code, HTTP
+status, and short message only to choose a rule; it never returns the input
+message, so tokens or raw provider payloads cannot leak into a report.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+
+# Ordered: the first matching rule wins, so specific product errors precede
+# generic HTTP-status fallbacks.
+RULES: tuple[dict[str, Any], ...] = (
+    {
+        "code": "adc_invalid_scope",
+        "patterns": (r"invalid_scope",),
+        "prerequisite": "oauth-scope-request",
+        "nextAction": "Re-run the ADC login or impersonation command requesting only the exact allowlisted scope for this provider (see the scope allowlist); do not reuse a token minted without that scope.",
+    },
+    {
+        "code": "token_scope_insufficient",
+        "patterns": (r"ACCESS_TOKEN_SCOPE_INSUFFICIENT", r"insufficient(?:_| )(?:authentication )?scopes?", r"Request had insufficient authentication scopes"),
+        "prerequisite": "oauth-granted-scope",
+        "nextAction": "Mint a new short-lived token that includes the provider's required scope, then repeat the same read-only request.",
+    },
+    {
+        "code": "redirect_uri_mismatch",
+        "patterns": (r"redirect_uri_mismatch",),
+        "prerequisite": "oauth-client-redirect-uri",
+        "nextAction": "Add the exact callback URL used by this connect path to the OAuth client's authorized redirect URIs, or switch to the client that already lists it.",
+    },
+    {
+        "code": "oauth_consent_not_configured",
+        "patterns": (r"consent screen", r"OAuth consent", r"access_denied.*(?:not completed|verification)", r"app (?:is )?(?:not verified|blocked)", r"org_internal"),
+        "prerequisite": "oauth-consent-configuration",
+        "nextAction": "Configure the OAuth consent screen (user type, test users or verification status) in the Cloud project that owns the client, then reconnect.",
+    },
+    {
+        "code": "developer_token_prohibited",
+        "patterns": (r"DEVELOPER_TOKEN_PROHIBITED", r"developer token is not allowed with the project", r"DEVELOPER_TOKEN_(?:MISMATCH|INVALID_FOR_PROJECT)"),
+        "prerequisite": "ads-developer-token-project-pairing",
+        "nextAction": "Use the OAuth client from the Cloud project already paired with this developer token, or request access for the new project; one developer token is bound to one project.",
+    },
+    {
+        "code": "developer_token_not_approved",
+        "patterns": (r"DEVELOPER_TOKEN_NOT_APPROVED", r"only approved for use with test accounts", r"DEVELOPER_TOKEN_NOT_ON_ALLOWLIST"),
+        "prerequisite": "ads-developer-token-access-level",
+        "nextAction": "Apply for Basic or Standard access for the developer token, or run against a Google Ads test account until it is approved.",
+    },
+    {
+        "code": "developer_token_missing",
+        "patterns": (r"DEVELOPER_TOKEN_PARAMETER_MISSING", r"developer[- ]token (?:header )?(?:is )?(?:missing|required)", r"DEVELOPER_TOKEN_(?:INVALID|MISSING)"),
+        "prerequisite": "ads-developer-token",
+        "nextAction": "Install the developer token in the host secret store and send it as the developer-token header; record only its presence.",
+    },
+    {
+        "code": "login_customer_mismatch",
+        "patterns": (r"login[-_ ]customer[-_ ]id", r"LOGIN_CUSTOMER_ID", r"USER_PERMISSION_DENIED.*manager"),
+        "prerequisite": "ads-login-customer-id",
+        "nextAction": "Set login-customer-id to the manager account that links to the target customer (digits only), or omit it when the user has direct access.",
+    },
+    {
+        "code": "ads_user_permission_denied",
+        "patterns": (r"USER_PERMISSION_DENIED", r"CUSTOMER_NOT_FOUND", r"NOT_ADS_USER"),
+        "prerequisite": "ads-account-access",
+        "nextAction": "Grant the authenticated Google user access to the target Ads customer (or its manager), then repeat listAccessibleCustomers before any report.",
+    },
+    {
+        "code": "ga4_property_membership",
+        "patterns": (r"does not have sufficient permissions for this property", r"User does not have (?:sufficient )?permission.*propert", r"properties/\d+.*PERMISSION_DENIED"),
+        "prerequisite": "ga4-property-membership",
+        "nextAction": "Add the principal (user or service account email) to the GA4 property with Viewer or higher in Property Access Management.",
+    },
+    {
+        "code": "gsc_property_membership",
+        "patterns": (r"User does not have sufficient permission for site", r"sites/.*PERMISSION_DENIED"),
+        "prerequisite": "gsc-property-membership",
+        "nextAction": "Add the principal as a user of the exact Search Console property (URL-prefix or domain) being queried.",
+    },
+    {
+        "code": "api_disabled",
+        "patterns": (r"SERVICE_DISABLED", r"has not been used in project .* or it is disabled", r"API .*is disabled", r"accessNotConfigured"),
+        "prerequisite": "cloud-api-enablement",
+        "nextAction": "Enable this provider's API in the Cloud project that owns the OAuth client or service account, wait a few minutes, then retry.",
+    },
+    {
+        "code": "quota_exhausted",
+        "patterns": (r"RESOURCE_EXHAUSTED", r"RATE_LIMIT_EXCEEDED", r"quota (?:exceeded|exhausted)", r"rateLimitExceeded", r"RESOURCE_TEMPORARILY_EXHAUSTED"),
+        "prerequisite": "provider-quota",
+        "nextAction": "Stop retrying, wait for the quota window or request more quota; record the request as blocked rather than repeating it.",
+    },
+    {
+        "code": "iam_token_creator_missing",
+        "patterns": (r"iam\.serviceAccounts\.getAccessToken", r"serviceAccountTokenCreator"),
+        "prerequisite": "service-account-impersonation",
+        "nextAction": "Grant the caller roles/iam.serviceAccountTokenCreator on the target service account, then re-run the impersonation command.",
+    },
+    {
+        "code": "product_role_denied",
+        "patterns": (r"PERMISSION_DENIED", r"The caller does not have permission", r"forbidden"),
+        "prerequisite": "product-role",
+        "nextAction": "Grant the principal the needed product-level role on the selected resource; Cloud IAM alone does not grant product access.",
+    },
+    {
+        "code": "invalid_grant",
+        "patterns": (r"invalid_grant", r"Token has been expired or revoked", r"UNAUTHENTICATED", r"invalid_token"),
+        "prerequisite": "oauth-credential-validity",
+        "nextAction": "Reconnect the account to obtain a fresh credential; the stored token is expired or revoked.",
+    },
+)
+
+STATUS_FALLBACK = {
+    401: RULES[-1],
+    403: next(rule for rule in RULES if rule["code"] == "product_role_denied"),
+    429: next(rule for rule in RULES if rule["code"] == "quota_exhausted"),
+}
+
+UNKNOWN = {
+    "code": "unclassified",
+    "prerequisite": "unknown",
+    "nextAction": "Record the provider error code and HTTP status (no payload) and check the prerequisites in order: scope, consent, API enablement, product access, quota.",
+}
+
+
+def classify(error: Any = None, *, status: int | None = None, provider: str | None = None) -> dict[str, Any]:
+    """Return {code, prerequisite, nextAction, provider, httpStatus}; never echoes input text."""
+    if isinstance(error, dict):
+        status = status if status is not None else error.get("httpStatus", error.get("status"))
+        parts = [error.get(key) for key in ("code", "reason", "status", "message")]
+        text = " ".join(str(item) for item in parts if isinstance(item, (str, int)))
+        provider = provider or error.get("provider")
+    else:
+        text = str(error or "")
+    text = text[:2000]
+    rule = None
+    for candidate in RULES:
+        if any(re.search(pattern, text, re.IGNORECASE) for pattern in candidate["patterns"]):
+            rule = candidate
+            break
+    if rule is None and isinstance(status, int):
+        rule = STATUS_FALLBACK.get(status)
+    rule = rule or UNKNOWN
+    return {
+        "code": rule["code"],
+        "prerequisite": rule["prerequisite"],
+        "nextAction": rule["nextAction"],
+        "provider": provider if isinstance(provider, str) else None,
+        "httpStatus": status if isinstance(status, int) else None,
+    }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topy-ai/maggie",
-  "version": "0.7.48",
+  "version": "0.7.49",
   "description": "Install and manage Maggie Skills for AI coding agents",
   "license": "MIT",
   "type": "module",

package/references/google-integrations-runbook.md

@@ -119,6 +119,60 @@ selected `resource`. A report that only proves account discovery, or comes from
 the wrong browser account/property, is rejected before a write workflow can use
 it.
 
+## Failure remediation
+
+A failed check must name the one prerequisite that failed, not a generic
+"access denied". Put only the provider error code/reason and HTTP status in the
+row's optional `failure` field; the validator returns `remediation` with a
+stable `code`, the failed `prerequisite`, and one safe `nextAction`. It never
+echoes the input text. `maggie ops google-diagnose` applies the same mapping to
+one error.
+
+| Signal | Failed prerequisite | Safe next action |
+|---|---|---|
+| `invalid_scope` (ADC) | OAuth scope request | Re-run the ADC/impersonation command with the exact allowlisted scope |
+| `ACCESS_TOKEN_SCOPE_INSUFFICIENT` | Granted token scope | Mint a new token that includes the provider scope |
+| `redirect_uri_mismatch` | OAuth client redirect URI | Add the exact callback URL to the client, or use the client that lists it |
+| Consent screen not configured / app not verified | OAuth consent configuration | Configure user type, test users, or verification in the client's project |
+| `SERVICE_DISABLED` / `accessNotConfigured` | Cloud API enablement | Enable the API in the project that owns the client or service account |
+| `RESOURCE_EXHAUSTED` / HTTP 429 | Provider quota | Stop retrying; wait for the window or request quota; record `blocked` |
+| `DEVELOPER_TOKEN_PARAMETER_MISSING` | Ads developer token | Install the token in the host secret store; send the `developer-token` header |
+| `DEVELOPER_TOKEN_NOT_APPROVED` | Ads token access level | Apply for Basic/Standard access, or use a test account |
+| `DEVELOPER_TOKEN_PROHIBITED` | Developer token/project pairing | Use the OAuth client from the paired Cloud project, or request access for the new project |
+| `USER_PERMISSION_DENIED` with a manager | `login-customer-id` | Set it to the manager that links the target, or omit it for direct access |
+| `USER_PERMISSION_DENIED` / `CUSTOMER_NOT_FOUND` | Ads account access | Grant the user access to the customer or its manager |
+| GA4 "insufficient permissions for this property" | GA4 property membership | Add the principal to the property with Viewer or higher |
+| `iam.serviceAccounts.getAccessToken` denied | Service-account impersonation | Grant `roles/iam.serviceAccountTokenCreator` on the target service account |
+| Other `PERMISSION_DENIED` / HTTP 403 | Product role | Grant the product-level role; Cloud IAM alone is insufficient |
+| `invalid_grant` / HTTP 401 | Credential validity | Reconnect; the stored token is expired or revoked |
+
+## Google Ads read-only preflight and Keyword Planner
+
+`maggie ops google-ads-preflight` checks, in order and independently: customer
+and `login-customer-id` format (10 digits; hyphens stripped), developer-token
+presence (environment variable name only), the `adwords` scope via token
+introspection (token sent in a POST body, never a URL),
+`customers:listAccessibleCustomers`, the manager hierarchy through
+`customer_client` when a manager is used, a `customer` read (currency, manager,
+test-account flags), and Keyword Planner readiness. The Keyword Planner check
+reports `ready` without spending a request unless `--probe-keyword-planner` is
+passed, which sends one one-result `generateKeywordIdeas` call. Every failure
+carries the same `remediation` mapping as above.
+
+`maggie ops google-ads-keyword-ideas` sends read-only `generateKeywordIdeas`
+requests (keyword, URL, or keyword+URL seed; language and geo-target constants;
+bounded pagination) and normalizes each idea to `text`, `avgMonthlySearches`,
+`competition`, `competitionIndex`, and `lowTopOfPageBid`/`highTopOfPageBid`
+converted from micros into the customer currency.
+
+The adapter refuses any request outside `listAccessibleCustomers`,
+`googleAds:search`, and `generateKeywordIdeas`, so it cannot mutate campaigns,
+budgets, or keywords. The REST API version defaults to `v21` and can be set with
+`--api-version` or `MAGGIE_GOOGLE_ADS_API_VERSION`; check Google's sunset
+schedule and use a currently supported version. Keyword Planner volumes are
+estimates for planning and require an approved developer token on a real
+account; test accounts return no metrics.
+
 ## Capability matrix
 
 Every provider/resource row must expose this shape: