mcp-google-ads 1.8.0 → 1.11.0

package/dist/adRotationUpdate.d.ts

@@ -0,0 +1,3 @@
+export declare const AD_SERVING_OPTIMIZATION_STATUS: Record<string, number>;
+export declare const AD_SERVING_OPTIMIZATION_STATUS_ENUM_TO_NAME: Record<number, string>;
+export declare function buildAdRotationCampaignUpdate(resourceName: string, mode: string): Record<string, any>;

package/dist/adRotationUpdate.js

@@ -0,0 +1,30 @@
+const AD_SERVING_OPTIMIZATION_STATUS = {
+  OPTIMIZE: 2,
+  CONVERSION_OPTIMIZE: 3,
+  ROTATE: 4,
+  ROTATE_INDEFINITELY: 5
+};
+const AD_SERVING_OPTIMIZATION_STATUS_ENUM_TO_NAME = {
+  2: "OPTIMIZE",
+  3: "CONVERSION_OPTIMIZE",
+  4: "ROTATE",
+  5: "ROTATE_INDEFINITELY"
+};
+function buildAdRotationCampaignUpdate(resourceName, mode) {
+  const statusEnum = AD_SERVING_OPTIMIZATION_STATUS[mode];
+  if (statusEnum === void 0) {
+    throw new Error(
+      `Unsupported ad rotation mode: ${mode}. Expected one of ${Object.keys(AD_SERVING_OPTIMIZATION_STATUS).join(", ")}`
+    );
+  }
+  return {
+    resource_name: resourceName,
+    ad_serving_optimization_status: statusEnum
+  };
+}
+export {
+  AD_SERVING_OPTIMIZATION_STATUS,
+  AD_SERVING_OPTIMIZATION_STATUS_ENUM_TO_NAME,
+  buildAdRotationCampaignUpdate
+};
+//# sourceMappingURL=adRotationUpdate.js.map

package/dist/assetHelpers.d.ts

@@ -95,4 +95,66 @@ export declare function normalizeReplaceSitelinkArgs(raw: Record<string, unknown
     error: string;
 };
 export declare function buildReplaceSitelinkDryRun(args: ReplaceSitelinkArgs): ReplaceSitelinkDryRun;
+export interface AssetLinkCandidate {
+    resource_name: string;
+    attach_to: string;
+    parent_status: string;
+}
+export interface PartitionedAssetLinks<T extends AssetLinkCandidate = AssetLinkCandidate> {
+    active: T[];
+    skippedRemoved: T[];
+}
+export declare function partitionAssetLinksByParentStatus<T extends AssetLinkCandidate>(rows: T[]): PartitionedAssetLinks<T>;
+export interface CreateCalloutArgs {
+    customer_id?: string;
+    callout_text: string;
+    confirm?: boolean;
+}
+export interface CreateCalloutDryRun {
+    dry_run: true;
+    message: string;
+    customer_id: string;
+    callout_text: string;
+}
+export declare function normalizeCreateCalloutArgs(raw: Record<string, unknown> | undefined): CreateCalloutArgs | {
+    error: string;
+};
+export declare function buildCreateCalloutDryRun(args: CreateCalloutArgs): CreateCalloutDryRun;
+export declare const STRUCTURED_SNIPPET_HEADERS: readonly ["Amenities", "Brands", "Courses", "Degree programs", "Destinations", "Featured hotels", "Insurance coverage", "Models", "Neighborhoods", "Service catalog", "Shows", "Styles", "Types"];
+export interface CreateStructuredSnippetArgs {
+    customer_id?: string;
+    header: string;
+    values: string[];
+    confirm?: boolean;
+}
+export interface CreateStructuredSnippetDryRun {
+    dry_run: true;
+    message: string;
+    customer_id: string;
+    header: string;
+    values: string[];
+}
+export declare function normalizeCreateStructuredSnippetArgs(raw: Record<string, unknown> | undefined): CreateStructuredSnippetArgs | {
+    error: string;
+};
+export declare function buildCreateStructuredSnippetDryRun(args: CreateStructuredSnippetArgs): CreateStructuredSnippetDryRun;
+export declare const CUSTOMER_ASSET_FIELD_TYPES: readonly ["SITELINK", "CALLOUT", "STRUCTURED_SNIPPET"];
+export type CustomerAssetFieldType = (typeof CUSTOMER_ASSET_FIELD_TYPES)[number];
+export interface LinkAssetToCustomerArgs {
+    customer_id?: string;
+    asset_id: string;
+    field_type: CustomerAssetFieldType;
+    confirm?: boolean;
+}
+export interface LinkAssetToCustomerDryRun {
+    dry_run: true;
+    message: string;
+    customer_id: string;
+    asset_id: string;
+    field_type: CustomerAssetFieldType;
+}
+export declare function normalizeLinkAssetToCustomerArgs(raw: Record<string, unknown> | undefined): LinkAssetToCustomerArgs | {
+    error: string;
+};
+export declare function buildLinkAssetToCustomerDryRun(args: LinkAssetToCustomerArgs): LinkAssetToCustomerDryRun;
 export declare function buildPauseLinksDryRun(args: PauseAssetLinksArgs): PauseLinksDryRun;

package/dist/assetHelpers.js

@@ -188,6 +188,120 @@ function buildReplaceSitelinkDryRun(args) {
     warning: "Will create a NEW sitelink asset, re-link every campaign/ad-group/customer link currently pointing at old_asset_id, then remove the old links. The old Asset itself is NOT deleted and can still be re-used manually."
   };
 }
+function partitionAssetLinksByParentStatus(rows) {
+  const active = [];
+  const skippedRemoved = [];
+  for (const r of rows) {
+    (r.parent_status === "REMOVED" ? skippedRemoved : active).push(r);
+  }
+  return { active, skippedRemoved };
+}
+function normalizeCreateCalloutArgs(raw) {
+  const r = raw ?? {};
+  const customer_id = typeof r.customer_id === "string" ? r.customer_id : void 0;
+  const calloutText = validateSitelinkText(r.callout_text, "callout_text", 25);
+  if (!calloutText.ok) return { error: calloutText.error };
+  return {
+    customer_id,
+    callout_text: calloutText.value,
+    confirm: r.confirm === true || r.confirm === "true"
+  };
+}
+function buildCreateCalloutDryRun(args) {
+  return {
+    dry_run: true,
+    message: "DRY RUN. Nothing created. Pass confirm: true to actually create the callout asset.",
+    customer_id: args.customer_id ?? "",
+    callout_text: args.callout_text
+  };
+}
+const STRUCTURED_SNIPPET_HEADERS = [
+  "Amenities",
+  "Brands",
+  "Courses",
+  "Degree programs",
+  "Destinations",
+  "Featured hotels",
+  "Insurance coverage",
+  "Models",
+  "Neighborhoods",
+  "Service catalog",
+  "Shows",
+  "Styles",
+  "Types"
+];
+const STRUCTURED_SNIPPET_HEADERS_BY_LOWER = new Map(
+  STRUCTURED_SNIPPET_HEADERS.map((h) => [h.toLowerCase(), h])
+);
+function normalizeCreateStructuredSnippetArgs(raw) {
+  const r = raw ?? {};
+  const customer_id = typeof r.customer_id === "string" ? r.customer_id : void 0;
+  if (typeof r.header !== "string" || !r.header.trim()) {
+    return { error: "header must be a non-empty string" };
+  }
+  const canonicalHeader = STRUCTURED_SNIPPET_HEADERS_BY_LOWER.get(r.header.trim().toLowerCase());
+  if (!canonicalHeader) {
+    return {
+      error: `Unrecognized structured-snippet header "${r.header}". Must be one of: ${STRUCTURED_SNIPPET_HEADERS.join(", ")}.`
+    };
+  }
+  const rawValues = coerceArray(r.values);
+  if (!rawValues || rawValues.length < 3 || rawValues.length > 10) {
+    return { error: `values must be an array of 3-10 strings (got ${rawValues?.length ?? 0})` };
+  }
+  const values = [];
+  for (const v of rawValues) {
+    const validated = validateSitelinkText(v, "values entry", 25);
+    if (!validated.ok) return { error: validated.error };
+    values.push(validated.value);
+  }
+  return {
+    customer_id,
+    header: canonicalHeader,
+    values,
+    confirm: r.confirm === true || r.confirm === "true"
+  };
+}
+function buildCreateStructuredSnippetDryRun(args) {
+  return {
+    dry_run: true,
+    message: "DRY RUN. Nothing created. Pass confirm: true to actually create the structured snippet asset.",
+    customer_id: args.customer_id ?? "",
+    header: args.header,
+    values: args.values
+  };
+}
+const CUSTOMER_ASSET_FIELD_TYPES = ["SITELINK", "CALLOUT", "STRUCTURED_SNIPPET"];
+function normalizeLinkAssetToCustomerArgs(raw) {
+  const r = raw ?? {};
+  const customer_id = typeof r.customer_id === "string" ? r.customer_id : void 0;
+  const assetIdRaw = typeof r.asset_id === "string" ? r.asset_id.trim() : typeof r.asset_id === "number" ? String(r.asset_id) : "";
+  if (!assetIdRaw || !/^\d+$/.test(assetIdRaw)) {
+    return { error: `invalid asset_id: ${JSON.stringify(r.asset_id)}. Expected numeric asset ID.` };
+  }
+  if (typeof r.field_type !== "string" || !r.field_type.trim()) {
+    return { error: "field_type must be a non-empty string" };
+  }
+  const fieldType = r.field_type.trim().toUpperCase();
+  if (!CUSTOMER_ASSET_FIELD_TYPES.includes(fieldType)) {
+    return { error: `Unsupported field_type: "${r.field_type}". Supported values: ${CUSTOMER_ASSET_FIELD_TYPES.join(", ")}` };
+  }
+  return {
+    customer_id,
+    asset_id: assetIdRaw,
+    field_type: fieldType,
+    confirm: r.confirm === true || r.confirm === "true"
+  };
+}
+function buildLinkAssetToCustomerDryRun(args) {
+  return {
+    dry_run: true,
+    message: "DRY RUN. Nothing linked. Pass confirm: true to actually link the asset at the customer (account) level.",
+    customer_id: args.customer_id ?? "",
+    asset_id: args.asset_id,
+    field_type: args.field_type
+  };
+}
 function buildPauseLinksDryRun(args) {
   const would = {
     customer_asset: [],
@@ -208,15 +322,24 @@ function buildPauseLinksDryRun(args) {
   };
 }
 export {
+  CUSTOMER_ASSET_FIELD_TYPES,
+  STRUCTURED_SNIPPET_HEADERS,
+  buildCreateCalloutDryRun,
   buildCreateSitelinkDryRun,
+  buildCreateStructuredSnippetDryRun,
+  buildLinkAssetToCustomerDryRun,
   buildPauseLinksDryRun,
   buildReplaceSitelinkDryRun,
   buildUpdateUrlsDryRun,
+  normalizeCreateCalloutArgs,
   normalizeCreateSitelinkArgs,
+  normalizeCreateStructuredSnippetArgs,
+  normalizeLinkAssetToCustomerArgs,
   normalizePauseAssetLinksArgs,
   normalizeReplaceSitelinkArgs,
   normalizeUpdateAssetUrlsArgs,
   parseAssetLinkResourceName,
+  partitionAssetLinksByParentStatus,
   validateFinalUrls
 };
 //# sourceMappingURL=assetHelpers.js.map

package/dist/backfillDefaults.d.ts

@@ -0,0 +1,19 @@
+/** Extract the selected field paths from a GAQL query's SELECT clause. */
+export declare function extractSelectedFields(query: string): string[];
+/**
+ * Resolve a dotted GAQL field path (e.g. "ad_group.optimized_targeting_enabled")
+ * to its primitive type tag (e.g. "BOOL"). Returns undefined if the path can't
+ * be resolved, or if it resolves to a nested message/enum object rather than a
+ * scalar leaf -- callers only act on an exact string type match.
+ */
+export declare function resolveFieldType(fieldPath: string): string | undefined;
+/**
+ * Google Ads' REST API omits fields at their proto3 default value (e.g.
+ * `false`) entirely from the JSON body -- our tool then serializes the row
+ * with no key at all, indistinguishable from "not returned"/error. This
+ * backfills an explicit `false` for any selected BOOL leaf field missing from
+ * a row whose parent object IS present, so callers can trust that an absent
+ * boolean key never means "unknown" -- only a truly absent parent resource
+ * (e.g. a metrics-only row) is left untouched, never fabricated.
+ */
+export declare function backfillOmittedBooleans<T = any>(query: string, rows: T[]): T[];

package/dist/backfillDefaults.js

@@ -0,0 +1,57 @@
+import { parse as circJsonParse } from "circ-json";
+import fieldsMod from "google-ads-api/build/src/protos/autogen/fields.js";
+let cachedFieldDataTypes = null;
+function getFieldDataTypes() {
+  if (!cachedFieldDataTypes) {
+    cachedFieldDataTypes = circJsonParse(fieldsMod.fieldDataTypes);
+  }
+  return cachedFieldDataTypes;
+}
+function snakeToPascal(snake) {
+  return snake.split("_").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join("");
+}
+function extractSelectedFields(query) {
+  const match = query.match(/SELECT\s+(.*?)\s+FROM\s/is);
+  if (!match) return [];
+  return match[1].split(",").map((f) => f.trim()).filter(Boolean);
+}
+function resolveFieldType(fieldPath) {
+  const segments = fieldPath.split(".");
+  if (segments.length < 2) return void 0;
+  const types = getFieldDataTypes();
+  let current = types[snakeToPascal(segments[0])];
+  for (let i = 1; i < segments.length && current !== void 0; i++) {
+    if (typeof current !== "object") return void 0;
+    current = current[segments[i]];
+  }
+  return typeof current === "string" ? current : void 0;
+}
+function backfillOmittedBooleans(query, rows) {
+  const boolPaths = extractSelectedFields(query).filter((f) => resolveFieldType(f) === "BOOL");
+  if (boolPaths.length === 0) return rows;
+  for (const row of rows) {
+    for (const path of boolPaths) {
+      const segments = path.split(".");
+      const leaf = segments[segments.length - 1];
+      let parent = row;
+      let reachable = true;
+      for (let i = 0; i < segments.length - 1; i++) {
+        if (parent == null || typeof parent !== "object") {
+          reachable = false;
+          break;
+        }
+        parent = parent[segments[i]];
+      }
+      if (reachable && parent != null && typeof parent === "object" && !(leaf in parent)) {
+        parent[leaf] = false;
+      }
+    }
+  }
+  return rows;
+}
+export {
+  backfillOmittedBooleans,
+  extractSelectedFields,
+  resolveFieldType
+};
+//# sourceMappingURL=backfillDefaults.js.map

package/dist/biddingUpdate.d.ts

@@ -0,0 +1,18 @@
+export declare const BIDDING_TYPE_ENUM_TO_NAME: Record<number, string>;
+export declare function wouldDetachPortfolioStrategy(currentBiddingStrategyResource: string | null | undefined): currentBiddingStrategyResource is string;
+export declare class PortfolioDetachBlocked extends Error {
+    campaignId: string;
+    campaignName: string;
+    portfolioStrategyResource: string;
+    constructor(campaignId: string, campaignName: string, portfolioStrategyResource: string);
+}
+export declare const DEFAULT_MAGNITUDE_CEILING_PCT = 20;
+export declare function computeMagnitudeDeltaPct(oldValue: number | undefined | null, newValue: number | undefined | null): number | null;
+export declare function exceedsMagnitudeCeiling(oldValue: number | undefined | null, newValue: number | undefined | null, ceilingPct?: number): boolean;
+export declare function isStrategyLooseningChange(oldTargetMicros: number | undefined | null, newTargetMicros: number | undefined | null, oldStrategy: string, newStrategy: string): boolean;
+export interface BiddingUpdateOpts {
+    resourceName: string;
+    targetCpaMicros?: number;
+    targetRoas?: number;
+}
+export declare function buildBiddingCampaignUpdate(strategy: string, opts: BiddingUpdateOpts): Record<string, any>;

package/dist/biddingUpdate.js

@@ -0,0 +1,102 @@
+const BIDDING_TYPE_ENUM_TO_NAME = {
+  3: "MANUAL_CPC",
+  6: "TARGET_CPA",
+  8: "TARGET_ROAS",
+  9: "MAXIMIZE_CLICKS",
+  // API type TARGET_SPEND=9, exposed to callers as MAXIMIZE_CLICKS
+  10: "MAXIMIZE_CONVERSIONS",
+  11: "MAXIMIZE_CONVERSION_VALUE"
+};
+function wouldDetachPortfolioStrategy(currentBiddingStrategyResource) {
+  return typeof currentBiddingStrategyResource === "string" && currentBiddingStrategyResource.length > 0;
+}
+class PortfolioDetachBlocked extends Error {
+  campaignId;
+  campaignName;
+  portfolioStrategyResource;
+  constructor(campaignId, campaignName, portfolioStrategyResource) {
+    super(
+      `Campaign ${campaignId} ("${campaignName}") is attached to portfolio bid strategy ${portfolioStrategyResource}. This update would silently detach it. Use google_ads_detach_portfolio_bid_strategy instead if you intend to break the attachment.`
+    );
+    this.name = "PortfolioDetachBlocked";
+    this.campaignId = campaignId;
+    this.campaignName = campaignName;
+    this.portfolioStrategyResource = portfolioStrategyResource;
+  }
+}
+const DEFAULT_MAGNITUDE_CEILING_PCT = 20;
+function computeMagnitudeDeltaPct(oldValue, newValue) {
+  if (oldValue === void 0 || oldValue === null || oldValue === 0) return null;
+  if (newValue === void 0 || newValue === null) return null;
+  return (newValue - oldValue) / oldValue * 100;
+}
+function exceedsMagnitudeCeiling(oldValue, newValue, ceilingPct = DEFAULT_MAGNITUDE_CEILING_PCT) {
+  const delta = computeMagnitudeDeltaPct(oldValue, newValue);
+  if (delta === null) return false;
+  return Math.abs(delta) > ceilingPct;
+}
+const TARGET_BASED_STRATEGIES = /* @__PURE__ */ new Set(["TARGET_CPA", "TARGET_ROAS"]);
+function isStrategyLooseningChange(oldTargetMicros, newTargetMicros, oldStrategy, newStrategy) {
+  const hadTarget = typeof oldTargetMicros === "number" && oldTargetMicros > 0;
+  const hasTarget = typeof newTargetMicros === "number" && newTargetMicros > 0;
+  if (hadTarget && !hasTarget) return true;
+  if (TARGET_BASED_STRATEGIES.has(oldStrategy) && !TARGET_BASED_STRATEGIES.has(newStrategy)) {
+    return true;
+  }
+  return false;
+}
+function buildBiddingCampaignUpdate(strategy, opts) {
+  const { resourceName, targetCpaMicros, targetRoas } = opts;
+  const update = { resource_name: resourceName };
+  switch (strategy) {
+    // NOTE: the google-ads-api client derives the mutate field mask from
+    // populated fields and DROPS empty sub-messages ({}). A switch to Maximize
+    // Conversions / Maximize Conversion Value with no target must therefore
+    // carry an explicit zero sentinel (target_cpa_micros:0 / target_roas:0 ==
+    // "no target") so the field is non-empty and the mask includes it. An empty
+    // {} silently no-ops: the mutate returns success while the strategy never
+    // changes. (Same {target_cpa_micros:0} pattern used in the budget path.)
+    case "MAXIMIZE_CONVERSIONS":
+      update.maximize_conversions = {
+        target_cpa_micros: targetCpaMicros !== void 0 ? targetCpaMicros : 0
+      };
+      break;
+    case "MAXIMIZE_CONVERSION_VALUE":
+      update.maximize_conversion_value = {
+        target_roas: targetRoas !== void 0 ? targetRoas : 0
+      };
+      break;
+    case "TARGET_CPA":
+      if (targetCpaMicros === void 0) {
+        throw new Error("TARGET_CPA strategy requires target_cpa_dollars");
+      }
+      update.target_cpa = { target_cpa_micros: targetCpaMicros };
+      break;
+    case "TARGET_ROAS":
+      if (targetRoas === void 0) {
+        throw new Error("TARGET_ROAS strategy requires target_roas");
+      }
+      update.target_roas = { target_roas: targetRoas };
+      break;
+    case "MANUAL_CPC":
+      update.manual_cpc = {};
+      break;
+    case "MAXIMIZE_CLICKS":
+      update.target_spend = {};
+      break;
+    default:
+      throw new Error(`Unsupported strategy: ${strategy}`);
+  }
+  return update;
+}
+export {
+  BIDDING_TYPE_ENUM_TO_NAME,
+  DEFAULT_MAGNITUDE_CEILING_PCT,
+  PortfolioDetachBlocked,
+  buildBiddingCampaignUpdate,
+  computeMagnitudeDeltaPct,
+  exceedsMagnitudeCeiling,
+  isStrategyLooseningChange,
+  wouldDetachPortfolioStrategy
+};
+//# sourceMappingURL=biddingUpdate.js.map

package/dist/build-info.json

@@ -1,5 +1,5 @@
 {
-  "sha": "b3b7dab",
-  "builtAt": "2026-07-20T18:35:03.765Z",
+  "sha": "8219937",
+  "builtAt": "2026-09-09T04:33:00.640Z",
   "embeddedSecrets": true
 }

package/dist/campaignBuilder.js

@@ -22,7 +22,15 @@ function buildCampaignCreatePayload(input) {
     // Required for all new campaigns in API v23+. Must be a non-zero enum value
     // (proto3 strips default/zero values, so `false`/0 gets omitted and the API
     // rejects with "required field not present").
-    contains_eu_political_advertising: enums.EuPoliticalAdvertisingStatus?.DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING ?? 3
+    contains_eu_political_advertising: enums.EuPoliticalAdvertisingStatus?.DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING ?? 3,
+    // API defaults geo_target_type_setting.positive_geo_target_type to
+    // PRESENCE_OR_INTEREST when omitted, which serves ads worldwide to anyone
+    // "interested in" the targeted location regardless of correct geo_target_ids.
+    // Always PRESENCE — caught 3x in production (2026-07-20, 07-31, 08-01) via
+    // next-day monitoring because this field was never set at creation time.
+    geo_target_type_setting: {
+      positive_geo_target_type: enums.PositiveGeoTargetType.PRESENCE
+    }
   };
   if (channelType === "DEMAND_GEN") {
     campaign.network_settings = {
@@ -32,6 +40,7 @@ function buildCampaignCreatePayload(input) {
       target_partner_search_network: false
     };
     campaign.audience_setting = { use_audience_grouped: true };
+    campaign.demand_gen_campaign_settings = { upgraded_targeting: false };
   }
   if (input.start_date) campaign.start_date = input.start_date;
   if (input.end_date) campaign.end_date = input.end_date;

package/dist/claudeLabel.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Canonical Claude audit-label format for Google Ads entities.
+ *
+ * GLOBAL rule: every Claude-created/edited campaign, ad group, ad group ad, or
+ * ad group criterion is stamped with an audit label so a batch can be found and
+ * rolled back. (Only those four resource types have a label surface — budgets,
+ * bidding, tracking edits, shared-set negatives and assets do NOT, so a
+ * "label every mutation" invariant is unbuildable; this module governs only the
+ * label STRING.)
+ *
+ * Format (locked 2026-07-23): `claude-MM-DD-YY` optionally followed by a
+ * kebab-case description — `claude-MM-DD-YY-<desc>`:
+ *   - `claude-` prefix keeps the `label.name LIKE 'claude-%'` rollback filter,
+ *   - the 2-digit date isolates a day's batch,
+ *   - the description (recommended) says what the change was.
+ *
+ * Single source of truth: the generator, the validator, and the recognizer
+ * (used to avoid double-adding the auto label) all agree here, so the format
+ * can't drift between the apply path and the rollback queries.
+ */
+/** True iff `label` matches the canonical `claude-MM-DD-YY[-desc]` format. */
+export declare function isValidClaudeLabel(label: string): boolean;
+/**
+ * Recognizer for the auto-applied label (any date, any/no description). Used to
+ * strip it from a caller's extra labels so it isn't added twice. Deliberately
+ * looser than the validator on the description (matches any suffix) so it still
+ * recognizes a label even if an older/newer descriptor convention was used.
+ */
+export declare const AUTO_CLAUDE_LABEL_RE: RegExp;
+/**
+ * Build the canonical audit label for `date`, optionally with a `descriptor`.
+ * The descriptor is slugged to kebab-case and dropped if it slugs to empty.
+ * The output is always a string `isValidClaudeLabel` accepts.
+ */
+export declare function claudeAuditLabel(date: Date, descriptor?: string): string;

package/dist/claudeLabel.js

@@ -0,0 +1,37 @@
+const DATE = "(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\\d|3[01])-\\d{2}";
+const DESC = "(?:-[a-z0-9]+(?:-[a-z0-9]+)*)?";
+const VALID_LABEL_RE = new RegExp(`^claude-${DATE}${DESC}$`);
+function isValidClaudeLabel(label) {
+  return VALID_LABEL_RE.test(label);
+}
+const AUTO_CLAUDE_LABEL_RE = new RegExp(`^claude-${DATE}(?:-.+)?$`, "i");
+const MAX_LABEL_LEN = 80;
+function slugify(descriptor) {
+  const slug = descriptor.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return slug;
+}
+function boundDescriptor(slug, budget) {
+  if (slug.length <= budget) return slug;
+  const clipped = slug.slice(0, budget);
+  const lastHyphen = clipped.lastIndexOf("-");
+  const kept = lastHyphen > 0 ? clipped.slice(0, lastHyphen) : clipped;
+  return kept.replace(/-+$/g, "");
+}
+function claudeAuditLabel(date, descriptor) {
+  const mm = String(date.getMonth() + 1).padStart(2, "0");
+  const dd = String(date.getDate()).padStart(2, "0");
+  const yy = String(date.getFullYear()).slice(-2);
+  const base = `claude-${mm}-${dd}-${yy}`;
+  if (!descriptor) return base;
+  let slug = slugify(descriptor);
+  if (!slug) return base;
+  const budget = MAX_LABEL_LEN - base.length - 1;
+  slug = boundDescriptor(slug, budget);
+  return slug ? `${base}-${slug}` : base;
+}
+export {
+  AUTO_CLAUDE_LABEL_RE,
+  claudeAuditLabel,
+  isValidClaudeLabel
+};
+//# sourceMappingURL=claudeLabel.js.map

package/dist/gaqlSharedSetGuard.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Query-time guard for the campaign_shared_set REMOVED-link trap.
+ *
+ * GAQL's `campaign_shared_set` resource returns links in every status, including
+ * REMOVED. A query that lists a shared list's campaigns WITHOUT filtering
+ * `campaign_shared_set.status = 'ENABLED'` therefore shows campaigns the list was
+ * UNLINKED from as if it were still attached.
+ *
+ * Origin: 2026-07-23 — a verify agent read `FROM campaign_shared_set` without the
+ * status filter, saw a REMOVED "Compliance Negatives" link, and reported a
+ * completed shared-set swap as "incomplete" (nearly triggering 5 needless unlinks).
+ * Memory alone can't help a subagent; this warning rides in the tool result every
+ * caller sees. Scoped tightly to campaign_shared_set to avoid warning-fatigue.
+ *
+ * Returns a warning string when the trap is possible, else null. Never blocks —
+ * some queries legitimately want removed rows.
+ */
+export declare function sharedSetLinkWarning(query: string): string | null;

package/dist/gaqlSharedSetGuard.js

@@ -0,0 +1,11 @@
+function sharedSetLinkWarning(query) {
+  const q = (query || "").toLowerCase();
+  if (!/\bfrom\s+campaign_shared_set\b/.test(q)) return null;
+  const filtersStatus = /\bstatus\s*=\s*'enabled'/.test(q) || /\bstatus\s*!=\s*'removed'/.test(q) || /\bstatus\s+in\s*\([^)]*'enabled'/.test(q);
+  if (filtersStatus) return null;
+  return "\u26A0 campaign_shared_set returns REMOVED links too \u2014 this query has no ENABLED-status filter, so lists that were UNLINKED still appear as if attached (this caused a false 'swap incomplete' verdict on 2026-07-23). If you're checking whether a shared set is CURRENTLY attached, add: AND campaign_shared_set.status = 'ENABLED'.";
+}
+export {
+  sharedSetLinkWarning
+};
+//# sourceMappingURL=gaqlSharedSetGuard.js.map