@adport/provider-google 0.1.0

package/dist/index.js

@@ -0,0 +1,888 @@
+// src/client.ts
+import { AdportError } from "@adport/core";
+var TOKEN_URL = "https://oauth2.googleapis.com/token";
+var API_BASE = "https://googleads.googleapis.com";
+var DEFAULT_API_VERSION = "v24";
+function normalizeCustomerId(id) {
+  const normalized = id.replace(/^customers\//, "").replace(/-/g, "").trim();
+  if (!/^\d{10}$/.test(normalized)) {
+    throw new AdportError("INVALID_INPUT", `"${id}" is not a valid Google Ads customer id (expected 10 digits).`);
+  }
+  return normalized;
+}
+var GoogleAdsRestClient = class {
+  constructor(credentials, version = process.env.GOOGLE_ADS_API_VERSION ?? DEFAULT_API_VERSION, fetchImpl = fetch) {
+    this.credentials = credentials;
+    this.version = version;
+    this.fetchImpl = fetchImpl;
+  }
+  credentials;
+  version;
+  fetchImpl;
+  accessToken;
+  async getAccessToken() {
+    if (this.accessToken && this.accessToken.expiresAt > Date.now()) {
+      return this.accessToken.token;
+    }
+    const response = await this.fetchImpl(TOKEN_URL, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        client_id: this.credentials.clientId,
+        client_secret: this.credentials.clientSecret,
+        refresh_token: this.credentials.refreshToken,
+        grant_type: "refresh_token"
+      })
+    });
+    if (!response.ok) {
+      const body = await response.text();
+      throw new AdportError(
+        "PROVIDER_ERROR",
+        `Google OAuth token refresh failed (${response.status}). Re-run \`adport connect google\` if the refresh token was revoked.`,
+        safeJson(body)
+      );
+    }
+    const data = await response.json();
+    this.accessToken = { token: data.access_token, expiresAt: Date.now() + (data.expires_in - 60) * 1e3 };
+    return this.accessToken.token;
+  }
+  async request(path, init) {
+    const token = await this.getAccessToken();
+    const headers = {
+      authorization: `Bearer ${token}`,
+      "developer-token": this.credentials.developerToken,
+      "content-type": "application/json"
+    };
+    if (this.credentials.loginCustomerId) {
+      headers["login-customer-id"] = normalizeCustomerId(this.credentials.loginCustomerId);
+    }
+    const response = await this.fetchImpl(`${API_BASE}/${this.version}/${path}`, {
+      method: init.method,
+      headers,
+      body: init.body === void 0 ? void 0 : JSON.stringify(init.body)
+    });
+    const raw = await response.text();
+    if (!response.ok) {
+      throw new AdportError("PROVIDER_ERROR", formatGoogleAdsError(response.status, raw), safeJson(raw));
+    }
+    return raw ? JSON.parse(raw) : {};
+  }
+  async listAccessibleCustomers() {
+    const data = await this.request("customers:listAccessibleCustomers", {
+      method: "GET"
+    });
+    return (data.resourceNames ?? []).map((name) => name.replace("customers/", ""));
+  }
+  /** Paged GAQL search; accumulates rows up to options.maxRows (default 1000). */
+  async search(customerId, query, options = {}) {
+    const maxRows = options.maxRows ?? 1e3;
+    const rows = [];
+    let pageToken;
+    do {
+      const data = await this.request(
+        `customers/${normalizeCustomerId(customerId)}/googleAds:search`,
+        { method: "POST", body: { query, pageToken } }
+      );
+      rows.push(...data.results ?? []);
+      pageToken = data.nextPageToken;
+    } while (pageToken && rows.length < maxRows);
+    return rows.slice(0, maxRows);
+  }
+  /**
+   * Service-specific mutate (campaigns, campaignBudgets, adGroups, adGroupCriteria, adGroupAds).
+   * validateOnly=true is the server-side dry run.
+   */
+  async mutate(customerId, service, operations, { validateOnly }) {
+    return this.request(`customers/${normalizeCustomerId(customerId)}/${service}:mutate`, {
+      method: "POST",
+      body: { operations, validateOnly, partialFailure: false }
+    });
+  }
+  /** Cross-service atomic mutate (e.g. budget + campaign with temp resource ids). */
+  async googleAdsMutate(customerId, mutateOperations, { validateOnly }) {
+    return this.request(`customers/${normalizeCustomerId(customerId)}/googleAds:mutate`, {
+      method: "POST",
+      body: { mutateOperations, validateOnly, partialFailure: false }
+    });
+  }
+};
+function safeJson(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+}
+function formatGoogleAdsError(status, raw) {
+  const parsed = safeJson(raw);
+  const error = parsed?.error;
+  if (!error) return `Google Ads API error (HTTP ${status})`;
+  const lines = [];
+  let requestId;
+  for (const detail of error.details ?? []) {
+    requestId = requestId ?? detail.requestId;
+    for (const item of detail.errors ?? []) {
+      const path = (item.location?.fieldPathElements ?? []).map((el) => el.index !== void 0 ? `${el.fieldName}[${el.index}]` : el.fieldName).join(".");
+      lines.push(`${path ? `at ${path}: ` : ""}${item.message}`);
+    }
+  }
+  const head = `Google Ads API error (HTTP ${status}): ${error.message ?? "request failed"}`;
+  const tail = requestId ? ` [request-id: ${requestId}]` : "";
+  return lines.length > 0 ? `${head}
+  ${lines.join("\n  ")}${tail}` : `${head}${tail}`;
+}
+
+// src/provider.ts
+import {
+  AdportError as AdportError2,
+  resolveDateRange
+} from "@adport/core";
+var LEVEL_RESOURCE = {
+  account: "customer",
+  campaign: "campaign",
+  ad_group: "ad_group",
+  ad: "ad_group_ad"
+};
+var BASE_METRIC_FIELDS = {
+  spend: "metrics.cost_micros",
+  impressions: "metrics.impressions",
+  clicks: "metrics.clicks",
+  conversions: "metrics.conversions",
+  conversion_value: "metrics.conversions_value"
+};
+var GoogleAdsProvider = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  id = "google";
+  capabilities() {
+    return { serverDryRun: true };
+  }
+  async listAccounts() {
+    const ids = await this.client.listAccessibleCustomers();
+    const accounts = [];
+    for (const id of ids) {
+      try {
+        const rows = await this.client.search(
+          id,
+          "SELECT customer.id, customer.descriptive_name, customer.currency_code, customer.status, customer.manager FROM customer LIMIT 1",
+          { maxRows: 1 }
+        );
+        const customer = rows[0]?.customer ?? {};
+        accounts.push({
+          provider: this.id,
+          id,
+          name: customer.descriptiveName ?? `(account ${id})`,
+          currency: customer.currencyCode,
+          status: customer.manager ? `${customer.status ?? "UNKNOWN"} (manager)` : customer.status
+        });
+      } catch {
+        accounts.push({ provider: this.id, id, name: "(details unavailable)", status: "UNKNOWN" });
+      }
+    }
+    return accounts;
+  }
+  async report(query) {
+    const range = resolveDateRange(query.dateRange);
+    const resource = LEVEL_RESOURCE[query.level];
+    const accountIds = query.accountIds ?? (await this.listAccounts()).filter((a) => !a.status?.includes("manager")).map((a) => a.id);
+    const baseMetrics = /* @__PURE__ */ new Set();
+    for (const metric of query.metrics) {
+      const field = BASE_METRIC_FIELDS[metric];
+      if (field) baseMetrics.add(field);
+    }
+    const wants = (m) => query.metrics.includes(m);
+    if (wants("ctr")) ["metrics.clicks", "metrics.impressions"].forEach((f) => baseMetrics.add(f));
+    if (wants("cpc") || wants("cpa") || wants("cpm") || wants("roas")) baseMetrics.add("metrics.cost_micros");
+    if (wants("cpc")) baseMetrics.add("metrics.clicks");
+    if (wants("cpm")) baseMetrics.add("metrics.impressions");
+    if (wants("cpa")) baseMetrics.add("metrics.conversions");
+    if (wants("roas")) baseMetrics.add("metrics.conversions_value");
+    const entityFields = {
+      account: ["customer.id", "customer.descriptive_name", "customer.status"],
+      campaign: ["campaign.id", "campaign.name", "campaign.status"],
+      ad_group: ["ad_group.id", "ad_group.name", "ad_group.status", "campaign.name"],
+      ad: ["ad_group_ad.ad.id", "ad_group_ad.status", "ad_group.name"]
+    }[query.level];
+    const gaql = `SELECT ${[...entityFields, ...baseMetrics].join(", ")} FROM ${resource} WHERE segments.date BETWEEN '${range.start}' AND '${range.end}' PARAMETERS omit_unselected_resource_names=true`;
+    const rows = [];
+    for (const accountId of accountIds) {
+      const results = await this.client.search(accountId, gaql, { maxRows: query.limit ?? 1e3 });
+      for (const row of results) {
+        rows.push(this.toReportRow(row, accountId, query));
+      }
+    }
+    return { rows };
+  }
+  toReportRow(row, accountId, query) {
+    const metricsRaw = row.metrics ?? {};
+    const num = (key) => Number(metricsRaw[key] ?? 0);
+    const spend = num("costMicros") / 1e6;
+    const impressions = num("impressions");
+    const clicks = num("clicks");
+    const conversions = num("conversions");
+    const conversionValue = num("conversionsValue");
+    const all = {
+      spend: round2(spend),
+      impressions,
+      clicks,
+      conversions,
+      conversion_value: round2(conversionValue),
+      ctr: impressions > 0 ? round2(clicks / impressions * 100) : 0,
+      cpc: clicks > 0 ? round2(spend / clicks) : 0,
+      cpm: impressions > 0 ? round2(spend / impressions * 1e3) : 0,
+      cpa: conversions > 0 ? round2(spend / conversions) : 0,
+      roas: spend > 0 ? round2(conversionValue / spend) : 0
+    };
+    let entity;
+    switch (query.level) {
+      case "account": {
+        const customer = row.customer ?? {};
+        entity = { level: "account", id: String(customer.id ?? accountId), name: customer.descriptiveName ?? accountId, status: customer.status };
+        break;
+      }
+      case "campaign": {
+        const campaign = row.campaign ?? {};
+        entity = { level: "campaign", id: String(campaign.id ?? ""), name: campaign.name ?? "", status: campaign.status };
+        break;
+      }
+      case "ad_group": {
+        const adGroup = row.adGroup ?? {};
+        entity = { level: "ad_group", id: String(adGroup.id ?? ""), name: adGroup.name ?? "", status: adGroup.status };
+        break;
+      }
+      case "ad": {
+        const adGroupAd = row.adGroupAd ?? {};
+        entity = { level: "ad", id: String(adGroupAd.ad?.id ?? ""), name: `ad ${adGroupAd.ad?.id ?? "?"}`, status: adGroupAd.status };
+        break;
+      }
+    }
+    return {
+      provider: this.id,
+      accountId,
+      entity,
+      metrics: Object.fromEntries(query.metrics.map((m) => [m, all[m]]))
+    };
+  }
+  async gaqlSearch(input) {
+    const limit = Math.min(input.limit ?? 200, 1e4);
+    let query = `SELECT ${input.fields.join(", ")} FROM ${input.resource}`;
+    if (input.conditions?.length) query += ` WHERE ${input.conditions.join(" AND ")}`;
+    if (input.order_by?.length) query += ` ORDER BY ${input.order_by.join(", ")}`;
+    query += ` LIMIT ${limit} PARAMETERS omit_unselected_resource_names=true`;
+    return this.client.search(input.customer_id, query, { maxRows: limit });
+  }
+  async previewWrite(op, guard) {
+    const plan = await this.plan(op, guard);
+    await plan.execute(true);
+    return {
+      summary: plan.summary,
+      changes: plan.changes,
+      coercions: plan.coercions,
+      budgetDeltas: plan.budgetDeltas,
+      serverValidated: true
+    };
+  }
+  async applyWrite(op, guard) {
+    const plan = await this.plan(op, guard);
+    const resourceIds = await plan.execute(false);
+    return { applied: true, resourceIds };
+  }
+  // ---- write planning ------------------------------------------------------
+  async plan(op, guard) {
+    const cid = normalizeCustomerId(op.accountId);
+    const payload = op.payload;
+    switch (op.tool) {
+      case "google_create_campaign":
+        return this.planCreateCampaign(cid, payload, guard);
+      case "google_set_campaign_status":
+        return this.planSetCampaignStatus(cid, payload);
+      case "google_set_budget":
+        return this.planSetBudget(cid, payload);
+      case "google_create_ad_group":
+        return this.planCreateAdGroup(cid, payload);
+      case "google_set_ad_group_status":
+        return this.planSetAdGroupStatus(cid, payload);
+      case "google_add_keywords":
+        return this.planAddKeywords(cid, payload);
+      case "google_set_keyword_status":
+        return this.planSetKeywordStatus(cid, payload);
+      case "google_remove_keywords":
+        return this.planRemoveKeywords(cid, payload);
+      case "google_create_responsive_search_ad":
+        return this.planCreateRsa(cid, payload, guard);
+      case "google_set_bid_ceiling":
+        return this.planSetBidCeiling(cid, payload);
+      case "google_set_bidding_strategy":
+        return this.planSetBiddingStrategy(cid, payload);
+      default:
+        throw new AdportError2("PROVIDER_ERROR", `google: unsupported write tool ${op.tool}`);
+    }
+  }
+  async planCreateCampaign(cid, payload, guard) {
+    const coercions = [];
+    let status = payload.status ?? "ENABLED";
+    if (guard.forcePausedCreation && status === "ENABLED") {
+      status = "PAUSED";
+      coercions.push("status coerced to PAUSED by policy (paused_creation)");
+    }
+    const channelType = payload.channel_type ?? "SEARCH";
+    const budgetTempResource = `customers/${cid}/campaignBudgets/-1`;
+    const mutateOperations = [
+      {
+        campaignBudgetOperation: {
+          create: {
+            resourceName: budgetTempResource,
+            name: `Budget for ${payload.name} (${Date.now()})`,
+            amountMicros: String(payload.daily_budget_micros),
+            deliveryMethod: "STANDARD",
+            explicitlyShared: false
+          }
+        }
+      },
+      {
+        campaignOperation: {
+          create: {
+            name: payload.name,
+            status,
+            advertisingChannelType: channelType,
+            manualCpc: {},
+            campaignBudget: budgetTempResource
+          }
+        }
+      }
+    ];
+    return {
+      summary: `Create ${channelType} campaign "${payload.name}" (${status}), daily budget ${payload.daily_budget_micros} micros`,
+      changes: [
+        `+ campaign_budget ${payload.daily_budget_micros} micros/day (not shared)`,
+        `+ campaign "${payload.name}" status=${status} channel=${channelType} bidding=manual_cpc`
+      ],
+      coercions,
+      budgetDeltas: [{ target: `new campaign "${payload.name}" daily budget`, toMicros: payload.daily_budget_micros }],
+      execute: async (validateOnly) => {
+        const res = await this.client.googleAdsMutate(cid, mutateOperations, { validateOnly });
+        return (res.mutateOperationResponses ?? []).flatMap((r) => Object.values(r).map((v) => v.resourceName)).filter((r) => Boolean(r));
+      }
+    };
+  }
+  async planSetCampaignStatus(cid, payload) {
+    const current = await this.lookupCampaign(cid, payload.campaign_id);
+    const resourceName = `customers/${cid}/campaigns/${payload.campaign_id}`;
+    return {
+      summary: `Set campaign "${current.name}" status ${current.status} \u2192 ${payload.status}`,
+      changes: [`~ campaign ${payload.campaign_id} status ${current.status} \u2192 ${payload.status}`],
+      coercions: [],
+      budgetDeltas: [],
+      execute: async (validateOnly) => {
+        const res = await this.client.mutate(
+          cid,
+          "campaigns",
+          [{ update: { resourceName, status: payload.status }, updateMask: "status" }],
+          { validateOnly }
+        );
+        return (res.results ?? []).map((r) => r.resourceName ?? resourceName);
+      }
+    };
+  }
+  async planSetBudget(cid, payload) {
+    const current = await this.lookupCampaign(cid, payload.campaign_id);
+    const changes = [
+      `~ campaign_budget ${current.budgetResource} amount ${current.budgetMicros} \u2192 ${payload.daily_budget_micros}`
+    ];
+    if (current.budgetShared) {
+      changes.push("! this budget is SHARED \u2014 the change affects every campaign using it");
+    }
+    return {
+      summary: `Change "${current.name}" daily budget ${current.budgetMicros} \u2192 ${payload.daily_budget_micros} micros`,
+      changes,
+      coercions: [],
+      budgetDeltas: [
+        {
+          target: `campaign "${current.name}" daily budget`,
+          fromMicros: current.budgetMicros,
+          toMicros: payload.daily_budget_micros
+        }
+      ],
+      execute: async (validateOnly) => {
+        const res = await this.client.mutate(
+          cid,
+          "campaignBudgets",
+          [
+            {
+              update: {
+                resourceName: current.budgetResource,
+                amountMicros: String(payload.daily_budget_micros)
+              },
+              updateMask: "amount_micros"
+            }
+          ],
+          { validateOnly }
+        );
+        return (res.results ?? []).map((r) => r.resourceName ?? current.budgetResource);
+      }
+    };
+  }
+  async planCreateAdGroup(cid, payload) {
+    const campaign = await this.lookupCampaign(cid, payload.campaign_id);
+    const create = {
+      name: payload.name,
+      campaign: `customers/${cid}/campaigns/${payload.campaign_id}`,
+      status: "ENABLED",
+      type: "SEARCH_STANDARD"
+    };
+    if (payload.cpc_bid_micros) create.cpcBidMicros = String(payload.cpc_bid_micros);
+    return {
+      summary: `Create ad group "${payload.name}" in campaign "${campaign.name}"`,
+      changes: [`+ ad_group "${payload.name}" in campaign ${payload.campaign_id} (ENABLED \u2014 inherits campaign state)`],
+      coercions: [],
+      budgetDeltas: [],
+      execute: async (validateOnly) => {
+        const res = await this.client.mutate(cid, "adGroups", [{ create }], { validateOnly });
+        return (res.results ?? []).map((r) => r.resourceName ?? "");
+      }
+    };
+  }
+  async planSetAdGroupStatus(cid, payload) {
+    const resourceName = `customers/${cid}/adGroups/${payload.ad_group_id}`;
+    return {
+      summary: `Set ad group ${payload.ad_group_id} status \u2192 ${payload.status}`,
+      changes: [`~ ad_group ${payload.ad_group_id} status \u2192 ${payload.status}`],
+      coercions: [],
+      budgetDeltas: [],
+      execute: async (validateOnly) => {
+        const res = await this.client.mutate(
+          cid,
+          "adGroups",
+          [{ update: { resourceName, status: payload.status }, updateMask: "status" }],
+          { validateOnly }
+        );
+        return (res.results ?? []).map((r) => r.resourceName ?? resourceName);
+      }
+    };
+  }
+  async planAddKeywords(cid, payload) {
+    const operations = payload.keywords.map((kw) => ({
+      create: {
+        adGroup: `customers/${cid}/adGroups/${payload.ad_group_id}`,
+        status: "ENABLED",
+        negative: payload.negative ?? false,
+        keyword: { text: kw.text, matchType: kw.match_type }
+      }
+    }));
+    const kind = payload.negative ? "negative keywords" : "keywords";
+    return {
+      summary: `Add ${payload.keywords.length} ${kind} to ad group ${payload.ad_group_id}`,
+      changes: payload.keywords.map((kw) => `+ ${payload.negative ? "negative " : ""}keyword [${kw.match_type}] "${kw.text}"`),
+      coercions: [],
+      budgetDeltas: [],
+      execute: async (validateOnly) => {
+        const res = await this.client.mutate(cid, "adGroupCriteria", operations, { validateOnly });
+        return (res.results ?? []).map((r) => r.resourceName ?? "");
+      }
+    };
+  }
+  async planSetKeywordStatus(cid, payload) {
+    const resourceName = `customers/${cid}/adGroupCriteria/${payload.ad_group_id}~${payload.criterion_id}`;
+    return {
+      summary: `Set keyword criterion ${payload.criterion_id} status \u2192 ${payload.status}`,
+      changes: [`~ ad_group_criterion ${payload.ad_group_id}~${payload.criterion_id} status \u2192 ${payload.status}`],
+      coercions: [],
+      budgetDeltas: [],
+      execute: async (validateOnly) => {
+        const res = await this.client.mutate(
+          cid,
+          "adGroupCriteria",
+          [{ update: { resourceName, status: payload.status }, updateMask: "status" }],
+          { validateOnly }
+        );
+        return (res.results ?? []).map((r) => r.resourceName ?? resourceName);
+      }
+    };
+  }
+  async planRemoveKeywords(cid, payload) {
+    const resourceNames = payload.criterion_ids.map(
+      (id) => `customers/${cid}/adGroupCriteria/${payload.ad_group_id}~${id}`
+    );
+    return {
+      summary: `PERMANENTLY remove ${resourceNames.length} keyword criteria from ad group ${payload.ad_group_id}`,
+      changes: resourceNames.map((r) => `- ${r}`),
+      coercions: [],
+      budgetDeltas: [],
+      execute: async (validateOnly) => {
+        const res = await this.client.mutate(
+          cid,
+          "adGroupCriteria",
+          resourceNames.map((remove) => ({ remove })),
+          { validateOnly }
+        );
+        return (res.results ?? []).map((r) => r.resourceName ?? "");
+      }
+    };
+  }
+  async planCreateRsa(cid, payload, guard) {
+    validateRsa(payload);
+    const coercions = [];
+    const status = guard.forcePausedCreation ? "PAUSED" : "ENABLED";
+    if (guard.forcePausedCreation) coercions.push("ad created PAUSED by policy (paused_creation)");
+    const create = {
+      adGroup: `customers/${cid}/adGroups/${payload.ad_group_id}`,
+      status,
+      ad: {
+        finalUrls: payload.final_urls,
+        responsiveSearchAd: {
+          headlines: payload.headlines.map((text) => ({ text })),
+          descriptions: payload.descriptions.map((text) => ({ text })),
+          ...payload.path1 ? { path1: payload.path1 } : {},
+          ...payload.path2 ? { path2: payload.path2 } : {}
+        }
+      }
+    };
+    return {
+      summary: `Create responsive search ad (${payload.headlines.length} headlines, ${payload.descriptions.length} descriptions) in ad group ${payload.ad_group_id}`,
+      changes: [`+ responsive_search_ad in ad_group ${payload.ad_group_id} status=${status}`],
+      coercions,
+      budgetDeltas: [],
+      execute: async (validateOnly) => {
+        const res = await this.client.mutate(cid, "adGroupAds", [{ create }], { validateOnly });
+        return (res.results ?? []).map((r) => r.resourceName ?? "");
+      }
+    };
+  }
+  /** CPC ceilings exist on TARGET_SPEND (Maximize clicks) and TARGET_IMPRESSION_SHARE. */
+  async planSetBidCeiling(cid, payload) {
+    const current = await this.lookupCampaignBidding(cid, payload.campaign_id);
+    const resourceName = `customers/${cid}/campaigns/${payload.campaign_id}`;
+    let update;
+    let updateMask;
+    if (current.strategyType === "TARGET_SPEND") {
+      update = { resourceName, targetSpend: { cpcBidCeilingMicros: String(payload.cpc_bid_ceiling_micros) } };
+      updateMask = "target_spend.cpc_bid_ceiling_micros";
+    } else if (current.strategyType === "TARGET_IMPRESSION_SHARE") {
+      update = {
+        resourceName,
+        targetImpressionShare: { cpcBidCeilingMicros: String(payload.cpc_bid_ceiling_micros) }
+      };
+      updateMask = "target_impression_share.cpc_bid_ceiling_micros";
+    } else {
+      throw new AdportError2(
+        "PROVIDER_ERROR",
+        `google: campaign "${current.name}" uses ${current.strategyType} bidding, which has no CPC bid ceiling. Use google_set_bidding_strategy to switch strategy (e.g. MAXIMIZE_CLICKS supports a ceiling).`
+      );
+    }
+    return {
+      summary: `Set "${current.name}" CPC bid ceiling ${current.cpcBidCeilingMicros ?? "(unset)"} \u2192 ${payload.cpc_bid_ceiling_micros} micros (${current.strategyType})`,
+      changes: [
+        `~ campaign ${payload.campaign_id} ${updateMask} ${current.cpcBidCeilingMicros ?? "(unset)"} \u2192 ${payload.cpc_bid_ceiling_micros}`
+      ],
+      coercions: [],
+      budgetDeltas: [],
+      execute: async (validateOnly) => {
+        const res = await this.client.mutate(cid, "campaigns", [{ update, updateMask }], { validateOnly });
+        return (res.results ?? []).map((r) => r.resourceName ?? resourceName);
+      }
+    };
+  }
+  async planSetBiddingStrategy(cid, payload) {
+    if (payload.target_cpa_micros && payload.strategy !== "MAXIMIZE_CONVERSIONS") {
+      throw new AdportError2("INVALID_INPUT", "target_cpa_micros only applies to MAXIMIZE_CONVERSIONS");
+    }
+    if (payload.target_roas && payload.strategy !== "MAXIMIZE_CONVERSION_VALUE") {
+      throw new AdportError2("INVALID_INPUT", "target_roas only applies to MAXIMIZE_CONVERSION_VALUE");
+    }
+    if (payload.cpc_bid_ceiling_micros && payload.strategy !== "MAXIMIZE_CLICKS") {
+      throw new AdportError2("INVALID_INPUT", "cpc_bid_ceiling_micros only applies to MAXIMIZE_CLICKS (target spend)");
+    }
+    const current = await this.lookupCampaignBidding(cid, payload.campaign_id);
+    const resourceName = `customers/${cid}/campaigns/${payload.campaign_id}`;
+    let strategyField;
+    let updateMask;
+    const details = [];
+    switch (payload.strategy) {
+      case "MANUAL_CPC":
+        strategyField = { manualCpc: {} };
+        updateMask = "manual_cpc";
+        break;
+      case "MAXIMIZE_CLICKS":
+        strategyField = {
+          targetSpend: payload.cpc_bid_ceiling_micros ? { cpcBidCeilingMicros: String(payload.cpc_bid_ceiling_micros) } : {}
+        };
+        updateMask = payload.cpc_bid_ceiling_micros ? "target_spend.cpc_bid_ceiling_micros" : "target_spend";
+        if (payload.cpc_bid_ceiling_micros) details.push(`ceiling ${payload.cpc_bid_ceiling_micros} micros`);
+        break;
+      case "MAXIMIZE_CONVERSIONS":
+        strategyField = {
+          maximizeConversions: payload.target_cpa_micros ? { targetCpaMicros: String(payload.target_cpa_micros) } : {}
+        };
+        updateMask = payload.target_cpa_micros ? "maximize_conversions.target_cpa_micros" : "maximize_conversions";
+        if (payload.target_cpa_micros) details.push(`target CPA ${payload.target_cpa_micros} micros`);
+        break;
+      case "MAXIMIZE_CONVERSION_VALUE":
+        strategyField = {
+          maximizeConversionValue: payload.target_roas ? { targetRoas: payload.target_roas } : {}
+        };
+        updateMask = payload.target_roas ? "maximize_conversion_value.target_roas" : "maximize_conversion_value";
+        if (payload.target_roas) details.push(`target ROAS ${payload.target_roas}`);
+        break;
+    }
+    return {
+      summary: `Switch "${current.name}" bidding ${current.strategyType} \u2192 ${payload.strategy}` + (details.length > 0 ? ` (${details.join(", ")})` : ""),
+      changes: [`~ campaign ${payload.campaign_id} bidding_strategy ${current.strategyType} \u2192 ${payload.strategy}`],
+      coercions: [],
+      budgetDeltas: [],
+      execute: async (validateOnly) => {
+        const res = await this.client.mutate(
+          cid,
+          "campaigns",
+          [{ update: { resourceName, ...strategyField }, updateMask }],
+          { validateOnly }
+        );
+        return (res.results ?? []).map((r) => r.resourceName ?? resourceName);
+      }
+    };
+  }
+  async lookupCampaignBidding(cid, campaignId) {
+    const rows = await this.client.search(
+      cid,
+      `SELECT campaign.name, campaign.bidding_strategy_type, campaign.target_spend.cpc_bid_ceiling_micros, campaign.target_impression_share.cpc_bid_ceiling_micros FROM campaign WHERE campaign.id = ${Number(campaignId)} LIMIT 1`,
+      { maxRows: 1 }
+    );
+    const row = rows[0];
+    if (!row) {
+      throw new AdportError2("PROVIDER_ERROR", `google: campaign ${campaignId} not found in account ${cid}`);
+    }
+    const campaign = row.campaign;
+    const ceiling = campaign.targetSpend?.cpcBidCeilingMicros ?? campaign.targetImpressionShare?.cpcBidCeilingMicros;
+    return {
+      name: campaign.name ?? campaignId,
+      strategyType: campaign.biddingStrategyType ?? "UNKNOWN",
+      cpcBidCeilingMicros: ceiling !== void 0 ? Number(ceiling) : void 0
+    };
+  }
+  async lookupCampaign(cid, campaignId) {
+    const rows = await this.client.search(
+      cid,
+      `SELECT campaign.name, campaign.status, campaign.campaign_budget, campaign_budget.resource_name, campaign_budget.amount_micros, campaign_budget.explicitly_shared FROM campaign WHERE campaign.id = ${Number(campaignId)} LIMIT 1`,
+      { maxRows: 1 }
+    );
+    const row = rows[0];
+    if (!row) {
+      throw new AdportError2("PROVIDER_ERROR", `google: campaign ${campaignId} not found in account ${cid}`);
+    }
+    const campaign = row.campaign;
+    const budget = row.campaignBudget ?? {};
+    return {
+      name: campaign.name ?? campaignId,
+      status: campaign.status ?? "UNKNOWN",
+      budgetResource: budget.resourceName ?? "",
+      budgetMicros: Number(budget.amountMicros ?? 0),
+      budgetShared: budget.explicitlyShared ?? false
+    };
+  }
+};
+function validateRsa(payload) {
+  const problems = [];
+  if (payload.headlines.length < 3 || payload.headlines.length > 15) problems.push("3\u201315 headlines required");
+  if (payload.descriptions.length < 2 || payload.descriptions.length > 4) problems.push("2\u20134 descriptions required");
+  if (payload.final_urls.length < 1) problems.push("at least one final_url required");
+  for (const h of payload.headlines) if (h.length > 30) problems.push(`headline over 30 chars: "${h}"`);
+  for (const d of payload.descriptions) if (d.length > 90) problems.push(`description over 90 chars: "${d}"`);
+  if (problems.length > 0) {
+    throw new AdportError2("INVALID_INPUT", `Responsive search ad invalid: ${problems.join("; ")}`);
+  }
+}
+function round2(n) {
+  return Math.round(n * 100) / 100;
+}
+
+// src/tools.ts
+import { defineTool, guardedWriteTool } from "@adport/core";
+import { z } from "zod";
+var statusSchema = z.enum(["ENABLED", "PAUSED"]);
+var matchTypeSchema = z.enum(["EXACT", "PHRASE", "BROAD"]);
+function googleTools(provider) {
+  return [
+    defineTool({
+      name: "google_gaql",
+      namespace: "google",
+      description: `Run a structured Google Ads (GAQL) query: pick a resource (campaign, ad_group, keyword_view, change_event, ...), fields (e.g. campaign.name, metrics.clicks, segments.date), optional conditions and ordering. Conditions are raw GAQL predicates, e.g. "segments.date DURING LAST_7_DAYS" or "campaign.status = 'ENABLED'".`,
+      input: z.object({
+        customer_id: z.string().describe("10-digit account id, dashes ok"),
+        resource: z.string().min(1),
+        fields: z.array(z.string()).min(1),
+        conditions: z.array(z.string()).optional(),
+        order_by: z.array(z.string()).optional(),
+        limit: z.number().int().positive().max(1e4).default(200)
+      }),
+      annotations: { readOnly: true },
+      async handler(input) {
+        const rows = await provider.gaqlSearch(input);
+        return { rows, row_count: rows.length };
+      }
+    }),
+    guardedWriteTool({
+      name: "google_create_campaign",
+      namespace: "google",
+      description: "Create a Google Ads campaign with its own (non-shared) daily budget, atomically. Manual CPC bidding; refine later.",
+      provider: "google",
+      kind: "create",
+      payload: z.object({
+        name: z.string().min(1),
+        daily_budget_micros: z.number().int().positive().describe("1 currency unit = 1,000,000 micros"),
+        channel_type: z.enum(["SEARCH", "DISPLAY", "SHOPPING", "VIDEO", "PERFORMANCE_MAX"]).default("SEARCH"),
+        status: statusSchema.optional()
+      })
+    }),
+    guardedWriteTool({
+      name: "google_set_campaign_status",
+      namespace: "google",
+      description: "Enable or pause a campaign.",
+      provider: "google",
+      kind: "update",
+      payload: z.object({ campaign_id: z.string(), status: statusSchema })
+    }),
+    guardedWriteTool({
+      name: "google_set_budget",
+      namespace: "google",
+      description: "Change a campaign's daily budget. The preview warns when the budget is shared across campaigns.",
+      provider: "google",
+      kind: "update",
+      payload: z.object({ campaign_id: z.string(), daily_budget_micros: z.number().int().positive() })
+    }),
+    guardedWriteTool({
+      name: "google_set_bid_ceiling",
+      namespace: "google",
+      description: "Set a campaign's max CPC bid ceiling (micros). Works for MAXIMIZE_CLICKS (target spend) and TARGET_IMPRESSION_SHARE strategies; fails with guidance for others.",
+      provider: "google",
+      kind: "update",
+      payload: z.object({
+        campaign_id: z.string(),
+        cpc_bid_ceiling_micros: z.number().int().positive().describe("1 currency unit = 1,000,000 micros")
+      })
+    }),
+    guardedWriteTool({
+      name: "google_set_bidding_strategy",
+      namespace: "google",
+      description: "Switch a campaign's bidding strategy: MANUAL_CPC, MAXIMIZE_CLICKS (optional cpc_bid_ceiling_micros), MAXIMIZE_CONVERSIONS (optional target_cpa_micros), MAXIMIZE_CONVERSION_VALUE (optional target_roas). Also updates the target of the current strategy when the strategy stays the same.",
+      provider: "google",
+      kind: "update",
+      payload: z.object({
+        campaign_id: z.string(),
+        strategy: z.enum(["MANUAL_CPC", "MAXIMIZE_CLICKS", "MAXIMIZE_CONVERSIONS", "MAXIMIZE_CONVERSION_VALUE"]),
+        target_cpa_micros: z.number().int().positive().optional(),
+        target_roas: z.number().positive().optional().describe("e.g. 3.5 = 350% return on ad spend"),
+        cpc_bid_ceiling_micros: z.number().int().positive().optional()
+      })
+    }),
+    guardedWriteTool({
+      name: "google_create_ad_group",
+      namespace: "google",
+      description: "Create a SEARCH_STANDARD ad group in a campaign.",
+      provider: "google",
+      kind: "create",
+      payload: z.object({
+        campaign_id: z.string(),
+        name: z.string().min(1),
+        cpc_bid_micros: z.number().int().positive().optional()
+      })
+    }),
+    guardedWriteTool({
+      name: "google_set_ad_group_status",
+      namespace: "google",
+      description: "Enable or pause an ad group.",
+      provider: "google",
+      kind: "update",
+      payload: z.object({ ad_group_id: z.string(), status: statusSchema })
+    }),
+    guardedWriteTool({
+      name: "google_add_keywords",
+      namespace: "google",
+      description: "Add keywords (or negative keywords) to an ad group.",
+      provider: "google",
+      kind: "create",
+      payload: z.object({
+        ad_group_id: z.string(),
+        keywords: z.array(z.object({ text: z.string().min(1), match_type: matchTypeSchema })).min(1),
+        negative: z.boolean().default(false)
+      })
+    }),
+    guardedWriteTool({
+      name: "google_set_keyword_status",
+      namespace: "google",
+      description: "Enable or pause a keyword criterion.",
+      provider: "google",
+      kind: "update",
+      payload: z.object({ ad_group_id: z.string(), criterion_id: z.string(), status: statusSchema })
+    }),
+    guardedWriteTool({
+      name: "google_remove_keywords",
+      namespace: "google",
+      description: "PERMANENTLY remove keyword criteria from an ad group. Prefer google_set_keyword_status to pause.",
+      provider: "google",
+      kind: "remove",
+      destructive: true,
+      payload: z.object({ ad_group_id: z.string(), criterion_ids: z.array(z.string()).min(1) })
+    }),
+    guardedWriteTool({
+      name: "google_create_responsive_search_ad",
+      namespace: "google",
+      description: "Create a responsive search ad (3\u201315 headlines \u226430 chars, 2\u20134 descriptions \u226490 chars).",
+      provider: "google",
+      kind: "create",
+      payload: z.object({
+        ad_group_id: z.string(),
+        headlines: z.array(z.string()).min(3).max(15),
+        descriptions: z.array(z.string()).min(2).max(4),
+        final_urls: z.array(z.string().url()).min(1),
+        path1: z.string().max(15).optional(),
+        path2: z.string().max(15).optional()
+      })
+    })
+  ];
+}
+
+// src/index.ts
+async function resolveGoogleCredentials(store) {
+  const record = await store.get("google");
+  if (record) {
+    const { developer_token, client_id, client_secret, refresh_token, login_customer_id } = record.data;
+    if (developer_token && client_id && client_secret && refresh_token) {
+      return {
+        developerToken: developer_token,
+        clientId: client_id,
+        clientSecret: client_secret,
+        refreshToken: refresh_token,
+        loginCustomerId: login_customer_id || void 0
+      };
+    }
+  }
+  const env = process.env;
+  if (env.GOOGLE_ADS_DEVELOPER_TOKEN && env.GOOGLE_ADS_CLIENT_ID && env.GOOGLE_ADS_CLIENT_SECRET && env.GOOGLE_ADS_REFRESH_TOKEN) {
+    return {
+      developerToken: env.GOOGLE_ADS_DEVELOPER_TOKEN,
+      clientId: env.GOOGLE_ADS_CLIENT_ID,
+      clientSecret: env.GOOGLE_ADS_CLIENT_SECRET,
+      refreshToken: env.GOOGLE_ADS_REFRESH_TOKEN,
+      loginCustomerId: env.GOOGLE_ADS_LOGIN_CUSTOMER_ID || void 0
+    };
+  }
+  return void 0;
+}
+async function createGoogleModule(store) {
+  const credentials = await resolveGoogleCredentials(store);
+  if (!credentials) return void 0;
+  const provider = new GoogleAdsProvider(new GoogleAdsRestClient(credentials));
+  return { provider, tools: googleTools(provider) };
+}
+export {
+  DEFAULT_API_VERSION,
+  GoogleAdsProvider,
+  GoogleAdsRestClient,
+  createGoogleModule,
+  formatGoogleAdsError,
+  googleTools,
+  normalizeCustomerId,
+  resolveGoogleCredentials
+};
+//# sourceMappingURL=index.js.map