@revclamp/google-ads-transparency-mcp-actor 1.0.1 → 1.0.3

package/.actor/actor.json

@@ -1,8 +1,8 @@
 {
   "actorSpecification": 1,
   "name": "google-ads-transparency-mcp-actor",
-  "title": "RevClamp AdPulse - For Google Ads Transparency Center (MCP & Apify Actor)",
-  "description": "Find verified Google Ads advertiser entities from any brand or domain (e.g. nike.com -> Nike, Inc.) and extract active and historical ad creatives (Text, Image, Video), preview URLs, and run dates with zero browser or proxy overhead. Independent intelligence tool by RevClamp; not affiliated with or endorsed by Google LLC.",
+  "title": "RevClamp AdPulse - Google Ads Transparency MCP & Actor",
+  "description": "Resolve verified Google Ads advertiser entities from any brand or domain and extract active or historical ad creatives (Text, Image, Video), ad copy, and run dates with zero browser overhead. Independent intelligence tool by RevClamp; not affiliated with or endorsed by Google LLC.",
   "version": "1.0",
   "buildTag": "latest",
   "minMemoryMbytes": 256,
@@ -13,5 +13,66 @@
     "memoryMbytes": 256
   },
   "input": "./input_schema.json",
+  "output": {
+    "actorOutputSchemaVersion": 1,
+    "title": "Google Ads Transparency Creatives & Run Summary",
+    "description": "Extracted Google Ads Transparency creative records (Default Dataset) and run billing/telemetry summary (Key-Value Store OUTPUT).",
+    "properties": {
+      "creatives": {
+        "type": "string",
+        "title": "Extracted Ad Creatives",
+        "description": "Verified advertiser ad creatives (Text, Image, Video), ad copy, destination domains, and active run dates.",
+        "template": "{{links.apiDefaultDatasetUrl}}/items"
+      },
+      "runSummary": {
+        "type": "string",
+        "title": "Run Summary & Telemetry (OUTPUT)",
+        "description": "Structured execution summary, resolved advertiser entities, pagination cursor, and billing receipt summary.",
+        "template": "{{links.apiDefaultKeyValueStoreUrl}}/records/OUTPUT"
+      }
+    }
+  },
+  "storages": {
+    "dataset": {
+      "actorSpecification": 1,
+      "fields": {
+        "type": "object",
+        "properties": {
+          "advertiserId": { "type": "string", "title": "Advertiser ID" },
+          "advertiserName": { "type": "string", "title": "Advertiser Name" },
+          "creativeId": { "type": "string", "title": "Creative ID" },
+          "format": { "type": "string", "title": "Ad Format" },
+          "regionCode": { "type": "string", "title": "Region Code" },
+          "firstSeenAtIso": { "type": "string", "title": "First Seen (ISO)" },
+          "lastSeenAtIso": { "type": "string", "title": "Last Seen (ISO)" },
+          "daysActive": { "type": "integer", "title": "Days Active" },
+          "previewUrl": { "type": "string", "title": "Preview Asset URL" },
+          "transparencyUrl": { "type": "string", "title": "Transparency Center URL" }
+        }
+      },
+      "views": {
+        "overview": {
+          "title": "Ad Creatives Overview",
+          "transformation": {
+            "fields": [
+              "advertiserId",
+              "advertiserName",
+              "creativeId",
+              "format",
+              "regionCode",
+              "firstSeenAtIso",
+              "lastSeenAtIso",
+              "daysActive",
+              "previewUrl",
+              "transparencyUrl"
+            ]
+          },
+          "display": {
+            "component": "table"
+          }
+        }
+      }
+    }
+  },
   "dockerfile": "../Dockerfile"
 }

package/.actor/input_schema.json

@@ -9,6 +9,8 @@
       "description": "Brand name or domain to match against verified Google Ads Transparency advertiser entities (e.g. 'nike.com', 'Stripe', 'shopify.com').",
       "maxLength": 512,
       "editor": "textfield",
+      "default": "Stripe",
+      "prefill": "Stripe",
       "example": "nike.com"
     },
     "advertiserId": {
@@ -62,7 +64,8 @@
       "description": "Maximum number of deduplicated ad creatives to extract in this run (1 to 200).",
       "minimum": 1,
       "maximum": 200,
-      "default": 40
+      "default": 40,
+      "prefill": 10
     },
     "pageToken": {
       "title": "Next-Page Cursor Token (Optional)",

package/actor_config.json

@@ -21,7 +21,7 @@
   ],
   "manifest": {
     "name": "google-ads-transparency-mcp-actor",
-    "version": "1.0.1",
+    "version": "1.0.3",
     "title": "RevClamp AdPulse - For Google Ads Transparency Center (MCP & Apify Actor)",
     "websiteUrl": "https://revclamp.com",
     "description": "Find verified Google Ads advertiser entities and extract active or historical ad creatives (Text, Image, Video), preview links, and run dates without browser or proxy overhead. Independent intelligence tool by RevClamp; not affiliated with or endorsed by Google LLC."

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@revclamp/google-ads-transparency-mcp-actor",
   "mcpName": "com.revclamp/google-ads-transparency-mcp-actor",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "type": "module",
   "description": "RevClamp AdPulse - For Google Ads Transparency Center (MCP & Apify Actor). Independent intelligence tool by RevClamp; not affiliated with or endorsed by Google LLC.",
   "homepage": "https://revclamp.com",

package/server.json

@@ -3,7 +3,7 @@
   "name": "com.revclamp/google-ads-transparency-mcp-actor",
   "title": "RevClamp AdPulse (Google Ads Transparency MCP)",
   "description": "Google Ads Transparency Center advertiser & creative intelligence MCP server by RevClamp.",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "websiteUrl": "https://revclamp.com",
   "repository": {
     "url": "https://github.com/lhphong09t2/revclamp-mcp",
@@ -27,7 +27,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@revclamp/google-ads-transparency-mcp-actor",
-      "version": "1.0.1",
+      "version": "1.0.3",
       "transport": {
         "type": "stdio"
       }

package/src/apify_actor.mjs

@@ -82,12 +82,25 @@ export function computeRunEconomicsTelemetry({
     Number(process.env.ACTOR_MEMORY_MBYTES || process.env.APIFY_MEMORY_MBYTES) ||
     ACTOR_PRICING_CONTRACT.maxMemoryMb,
   requestCount = 1,
+  unitPriceUsdc = ACTOR_PRICING_CONTRACT.priceUsdc,
+  actorStartFeeUsdc = ACTOR_PRICING_CONTRACT.actorStartFeeUsdc,
 } = {}) {
   const safeCount = Math.max(0, Math.floor(Number(billableCount) || 0));
   const safeChargedCount = Math.max(0, Math.floor(Number(chargedEventCount) || 0));
   const safeDurationMs = Math.max(1, Number(durationMs) || 1);
   const safeMemoryMb = Math.min(1024, Math.max(64, Number(memoryMb) || 256));
   const safeRequests = Math.max(1, Math.floor(Number(requestCount) || 1));
+  const resolvedUnitPriceUsdc =
+    Number.isFinite(Number(unitPriceUsdc)) && Number(unitPriceUsdc) > 0
+      ? Number(unitPriceUsdc)
+      : ACTOR_PRICING_CONTRACT.priceUsdc;
+  const resolvedNetPriceUsdc = Number(
+    (resolvedUnitPriceUsdc * (1 - ACTOR_PRICING_CONTRACT.platformFeeRate)).toFixed(6)
+  );
+  const resolvedStartFeeUsdc =
+    Number.isFinite(Number(actorStartFeeUsdc)) && Number(actorStartFeeUsdc) >= 0
+      ? Number(actorStartFeeUsdc)
+      : ACTOR_PRICING_CONTRACT.actorStartFeeUsdc;
 
   // Apify compute rate: $0.30 per GB-hour; 256MB = 0.25 GB -> $0.075/hour -> $0.00002083/sec
   const computeHours = safeDurationMs / 3600000;
@@ -95,10 +108,9 @@ export function computeRunEconomicsTelemetry({
     (safeMemoryMb / 1024) * computeHours * ACTOR_PRICING_CONTRACT.computeRatePerGbHourUsdc;
   const networkOverheadUsdc = safeRequests * 0.0000002;
   const totalRunCostUsdc = Number((computeCostUsdc + networkOverheadUsdc).toFixed(8));
-  const actorStartFeeUsdc = ACTOR_PRICING_CONTRACT.actorStartFeeUsdc;
 
   const configuredFloorMultiplier = Number(
-    (ACTOR_PRICING_CONTRACT.netPriceUsdc / ACTOR_PRICING_CONTRACT.costCeilingUsdc).toFixed(2)
+    (resolvedNetPriceUsdc / ACTOR_PRICING_CONTRACT.costCeilingUsdc).toFixed(2)
   );
 
   if (safeCount === 0) {
@@ -109,7 +121,7 @@ export function computeRunEconomicsTelemetry({
       durationMs: safeDurationMs,
       memoryMb: safeMemoryMb,
       requestCount: safeRequests,
-      actorStartFeeUsdc,
+      actorStartFeeUsdc: resolvedStartFeeUsdc,
       totalRunCostUsdc,
       actualCostPerEventUsdc: 0,
       costCeilingUsdc: ACTOR_PRICING_CONTRACT.costCeilingUsdc,
@@ -123,11 +135,11 @@ export function computeRunEconomicsTelemetry({
   }
 
   const actualCostPerEventUsdc = Number((totalRunCostUsdc / safeCount).toFixed(8));
-  const grossRevenueUsdc = Number((safeCount * ACTOR_PRICING_CONTRACT.priceUsdc).toFixed(6));
-  const netRevenueUsdc = Number((safeCount * ACTOR_PRICING_CONTRACT.netPriceUsdc).toFixed(6));
+  const grossRevenueUsdc = Number((safeCount * resolvedUnitPriceUsdc).toFixed(6));
+  const netRevenueUsdc = Number((safeCount * resolvedNetPriceUsdc).toFixed(6));
   const effectiveMarginMultiplier =
     actualCostPerEventUsdc > 0
-      ? Number((ACTOR_PRICING_CONTRACT.netPriceUsdc / actualCostPerEventUsdc).toFixed(2))
+      ? Number((resolvedNetPriceUsdc / actualCostPerEventUsdc).toFixed(2))
       : configuredFloorMultiplier;
 
   const withinCostCeiling = actualCostPerEventUsdc <= ACTOR_PRICING_CONTRACT.costCeilingUsdc;
@@ -142,7 +154,7 @@ export function computeRunEconomicsTelemetry({
     durationMs: safeDurationMs,
     memoryMb: safeMemoryMb,
     requestCount: safeRequests,
-    actorStartFeeUsdc,
+    actorStartFeeUsdc: resolvedStartFeeUsdc,
     totalRunCostUsdc,
     actualCostPerEventUsdc,
     costCeilingUsdc: ACTOR_PRICING_CONTRACT.costCeilingUsdc,
@@ -203,9 +215,25 @@ export async function loadApifyActorInput(
     return JSON.parse(raw);
   }
 
+  const isAtHome = env?.APIFY_IS_AT_HOME === '1' || env?.APIFY_IS_AT_HOME === 'true';
+  const applyAtHomeSchemaDefaults = (parsedInput) => {
+    if (
+      isAtHome &&
+      parsedInput &&
+      typeof parsedInput === 'object' &&
+      !Array.isArray(parsedInput) &&
+      !Object.prototype.hasOwnProperty.call(parsedInput, 'query') &&
+      !Object.prototype.hasOwnProperty.call(parsedInput, 'advertiserId') &&
+      !Object.prototype.hasOwnProperty.call(parsedInput, 'pageToken')
+    ) {
+      return { query: 'Stripe', ...parsedInput };
+    }
+    return parsedInput;
+  };
+
   if (env?.APIFY_INPUT_PATH && fs.existsSync(env.APIFY_INPUT_PATH)) {
     const raw = fs.readFileSync(env.APIFY_INPUT_PATH, 'utf8');
-    return JSON.parse(raw);
+    return applyAtHomeSchemaDefaults(raw && raw.trim() ? JSON.parse(raw) : {});
   }
 
   const localStorageDir =
@@ -224,7 +252,8 @@ export async function loadApifyActorInput(
         candidateName
       );
       if (fs.existsSync(localInputPath)) {
-        return JSON.parse(fs.readFileSync(localInputPath, 'utf8'));
+        const raw = fs.readFileSync(localInputPath, 'utf8');
+        return applyAtHomeSchemaDefaults(raw && raw.trim() ? JSON.parse(raw) : {});
       }
     }
   }
@@ -254,9 +283,11 @@ export async function loadApifyActorInput(
       });
       if (res.status === 200) {
         const text = await res.text();
-        if (text && text.trim()) {
-          return JSON.parse(text);
-        }
+        const parsed = text && text.trim() ? JSON.parse(text) : {};
+        return applyAtHomeSchemaDefaults(parsed);
+      }
+      if (res.status === 204 || res.status === 404) {
+        return applyAtHomeSchemaDefaults({});
       }
     } finally {
       clearTimeout(timer);
@@ -310,6 +341,19 @@ export function createApifyPlatformHooks(env = process.env, fetchImpl = globalTh
       env?.APIFY_API_BASE_URL,
       env?.APIFY_API_PUBLIC_BASE_URL
     );
+    let pricingInfoChargeEvents = null;
+    const rawPricingInfoEnv = env?.APIFY_ACTOR_PRICING_INFO || env?.ACTOR_PRICING_INFO;
+    if (rawPricingInfoEnv) {
+      try {
+        const parsedPricing = JSON.parse(String(rawPricingInfoEnv));
+        const eventsObj = parsedPricing?.pricingPerEvent?.actorChargeEvents;
+        if (eventsObj && typeof eventsObj === 'object') {
+          pricingInfoChargeEvents = eventsObj;
+        }
+      } catch {
+        pricingInfoChargeEvents = null;
+      }
+    }
     const rawMaxChargeStr =
       env?.ACTOR_MAX_TOTAL_CHARGE_USD !== undefined && env?.ACTOR_MAX_TOTAL_CHARGE_USD !== null
         ? String(env.ACTOR_MAX_TOTAL_CHARGE_USD).trim()
@@ -320,23 +364,28 @@ export function createApifyPlatformHooks(env = process.env, fetchImpl = globalTh
       .trim()
       .toLowerCase();
     const includeStartFee = includeStartFeeFlag !== '0' && includeStartFeeFlag !== 'false';
+    const pricingInfoStartFeeUsd = Number(
+      pricingInfoChargeEvents?.['apify-actor-start']?.eventPriceUsd
+    );
     const explicitStartFeeUsd =
       env?.ACTOR_START_FEE_USD !== undefined &&
       env?.ACTOR_START_FEE_USD !== null &&
       String(env.ACTOR_START_FEE_USD).trim() !== ''
         ? Number(env.ACTOR_START_FEE_USD)
-        : ACTOR_PRICING_CONTRACT.actorStartFeeUsdc;
+        : Number.isFinite(pricingInfoStartFeeUsd) && pricingInfoStartFeeUsd >= 0
+          ? pricingInfoStartFeeUsd
+          : ACTOR_PRICING_CONTRACT.actorStartFeeUsdc;
     const startFeeMicros =
       includeStartFee && Number.isFinite(explicitStartFeeUsd) && explicitStartFeeUsd >= 0
         ? Math.round(explicitStartFeeUsd * 1_000_000)
         : 0;
-    const unitPriceMicros = Math.round(ACTOR_PRICING_CONTRACT.priceUsdc * 1_000_000);
     const maxBudgetMicros = hasMaxChargeUsd ? Math.round(maxTotalChargeUsdRaw * 1_000_000) : 0;
-    const maxPayableEvents = hasMaxChargeUsd
-      ? Math.floor(Math.max(0, maxBudgetMicros - startFeeMicros) / unitPriceMicros)
-      : Infinity;
     let cumulativeChargedInAdapter = 0;
     let adapterChargeLimitLatched = false;
+    hooks.actorStartFeeUsdc =
+      includeStartFee && Number.isFinite(explicitStartFeeUsd) && explicitStartFeeUsd >= 0
+        ? explicitStartFeeUsd
+        : 0;
 
     if (kvsId) {
       const checkpointRecordUrl = `${apiBase}/v2/key-value-stores/${encodeURIComponent(kvsId)}/records/${ACTOR_PRICING_CONTRACT.checkpointKey}`;
@@ -470,15 +519,80 @@ export function createApifyPlatformHooks(env = process.env, fetchImpl = globalTh
 
     if (runId) {
       const chargeUrl = `${apiBase}/v2/actor-runs/${encodeURIComponent(runId)}/charge`;
+      const allowUnbilledAtHome = env?.ADPULSE_ALLOW_UNBILLED_AT_HOME === '1';
+      let unbilledOwnerTestLatched = false;
+      let latchedPlatformEventName = null;
+      const resolvePlatformEventAndPrice = (rawEventName) => {
+        const candidate = String(rawEventName || ACTOR_PRICING_CONTRACT.eventName);
+        const effectiveName =
+          latchedPlatformEventName ||
+          (() => {
+            if (pricingInfoChargeEvents) {
+              if (Object.prototype.hasOwnProperty.call(pricingInfoChargeEvents, candidate)) {
+                return candidate;
+              }
+              if (
+                candidate === 'ad-creative-scraped' ||
+                candidate === 'ad_transparency_creative_retrieved'
+              ) {
+                if (
+                  Object.prototype.hasOwnProperty.call(
+                    pricingInfoChargeEvents,
+                    'ad_transparency_creative_retrieved'
+                  )
+                ) {
+                  return 'ad_transparency_creative_retrieved';
+                }
+                if (
+                  Object.prototype.hasOwnProperty.call(
+                    pricingInfoChargeEvents,
+                    'ad-creative-scraped'
+                  )
+                ) {
+                  return 'ad-creative-scraped';
+                }
+              }
+            }
+            return candidate;
+          })();
+        const rawEventPrice = Number(pricingInfoChargeEvents?.[effectiveName]?.eventPriceUsd);
+        const unitPriceUsdc =
+          Number.isFinite(rawEventPrice) && rawEventPrice > 0
+            ? rawEventPrice
+            : ACTOR_PRICING_CONTRACT.priceUsdc;
+        return { eventName: effectiveName, unitPriceUsdc };
+      };
+      hooks.unitPriceUsdc = resolvePlatformEventAndPrice(
+        ACTOR_PRICING_CONTRACT.eventName
+      ).unitPriceUsdc;
       hooks.chargeEvent = async (receipt) => {
         const requestedCount = Math.max(0, Number(receipt?.count) || 0);
+        const { eventName: primaryEventName, unitPriceUsdc: resolvedUnitPriceUsdc } =
+          resolvePlatformEventAndPrice(receipt?.eventName);
+        hooks.unitPriceUsdc = resolvedUnitPriceUsdc;
+        if (unbilledOwnerTestLatched) {
+          return {
+            chargedCount: 0,
+            eventChargeLimitReached: false,
+            unbilledOwnerTestBypass: true,
+            chargedCreativeIds: [],
+            eventName: primaryEventName,
+            unitPriceUsdc: resolvedUnitPriceUsdc,
+          };
+        }
         if (adapterChargeLimitLatched) {
           return {
             chargedCount: 0,
             eventChargeLimitReached: true,
             chargedCreativeIds: [],
+            eventName: primaryEventName,
+            unitPriceUsdc: resolvedUnitPriceUsdc,
           };
         }
+        const unitPriceMicros = Math.round(resolvedUnitPriceUsdc * 1_000_000);
+        const maxPayableEvents = hasMaxChargeUsd
+          ? Math.floor(Math.max(0, maxBudgetMicros - startFeeMicros) / unitPriceMicros)
+          : Infinity;
         const remainingAllowance = Number.isFinite(maxPayableEvents)
           ? Math.max(0, maxPayableEvents - cumulativeChargedInAdapter)
           : requestedCount;
@@ -493,25 +607,65 @@ export function createApifyPlatformHooks(env = process.env, fetchImpl = globalTh
             chargedCount: 0,
             eventChargeLimitReached: Number.isFinite(maxPayableEvents),
             chargedCreativeIds: [],
+            eventName: primaryEventName,
+            unitPriceUsdc: resolvedUnitPriceUsdc,
           };
         }
 
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), 600);
-        try {
-          const res = await fetchImpl(chargeUrl, {
+        const postChargeRequest = async (eventNameToPost, idempotencyKeyToPost, signal) =>
+          fetchImpl(chargeUrl, {
             method: 'POST',
             headers: {
               authorization: `Bearer ${token}`,
               'content-type': 'application/json; charset=utf-8',
-              'idempotency-key': receipt.idempotencyKey,
+              'idempotency-key': idempotencyKeyToPost,
             },
             body: JSON.stringify({
-              eventName: receipt.eventName,
+              eventName: eventNameToPost,
               count: countToCharge,
             }),
-            signal: controller.signal,
+            signal,
           });
+
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 600);
+        try {
+          let effectiveEventName = primaryEventName;
+          let effectiveIdempotencyKey = receipt.idempotencyKey;
+          let res = await postChargeRequest(
+            primaryEventName,
+            receipt.idempotencyKey,
+            controller.signal
+          );
+          if (
+            res.status === 404 &&
+            !pricingInfoChargeEvents &&
+            !latchedPlatformEventName &&
+            (primaryEventName === 'ad-creative-scraped' ||
+              primaryEventName === 'ad_transparency_creative_retrieved')
+          ) {
+            const aliasEventName =
+              primaryEventName === 'ad-creative-scraped'
+                ? 'ad_transparency_creative_retrieved'
+                : 'ad-creative-scraped';
+            const aliasIdempotencyKey = `${receipt.idempotencyKey}-${aliasEventName}`;
+            const fallbackRes = await postChargeRequest(
+              aliasEventName,
+              aliasIdempotencyKey,
+              controller.signal
+            );
+            if (fallbackRes.status !== 404) {
+              res = fallbackRes;
+              effectiveEventName = aliasEventName;
+              effectiveIdempotencyKey = aliasIdempotencyKey;
+              if (
+                (fallbackRes.status >= 200 && fallbackRes.status < 300) ||
+                fallbackRes.status === 402
+              ) {
+                latchedPlatformEventName = aliasEventName;
+              }
+            }
+          }
           if (res.status === 402) {
             // Platform enforced spending ceiling (HTTP 402 Payment Required): latch so no further charge POSTs occur
             adapterChargeLimitLatched = true;
@@ -519,10 +673,50 @@ export function createApifyPlatformHooks(env = process.env, fetchImpl = globalTh
               chargedCount: 0,
               eventChargeLimitReached: true,
               chargedCreativeIds: [],
+              eventName: effectiveEventName,
+              unitPriceUsdc: resolvedUnitPriceUsdc,
+              idempotencyKey: effectiveIdempotencyKey,
             };
           }
+          if (allowUnbilledAtHome && (res.status === 405 || res.status === 403)) {
+            let isUnmonetizedNotAllowed = res.status === 405;
+            if (res.status === 403) {
+              try {
+                const errText = await res.text();
+                const errJson = errText && errText.trim() ? JSON.parse(errText) : null;
+                isUnmonetizedNotAllowed = errJson?.error?.type === 'operation-not-allowed';
+              } catch {
+                isUnmonetizedNotAllowed = false;
+              }
+            }
+            if (isUnmonetizedNotAllowed) {
+              unbilledOwnerTestLatched = true;
+              return {
+                chargedCount: 0,
+                eventChargeLimitReached: false,
+                unbilledOwnerTestBypass: true,
+                chargedCreativeIds: [],
+                eventName: effectiveEventName,
+                unitPriceUsdc: resolvedUnitPriceUsdc,
+                idempotencyKey: effectiveIdempotencyKey,
+              };
+            }
+          }
           if (res.status < 200 || res.status >= 300) {
-            throw new Error(`Apify Pay-per-Event charge HTTP ${res.status}`);
+            let errSuffix = '';
+            try {
+              const errText = await res.text();
+              if (errText && errText.trim()) {
+                const errJson = JSON.parse(errText);
+                const errType = errJson?.error?.type;
+                if (typeof errType === 'string' && /^[A-Za-z0-9_.:-]{1,64}$/.test(errType)) {
+                  errSuffix = ` (${errType})`;
+                }
+              }
+            } catch {
+              errSuffix = '';
+            }
+            throw new Error(`Apify Pay-per-Event charge HTTP ${res.status}${errSuffix}`);
           }
           const rawText = await res.text();
           const parsed = rawText && rawText.trim() ? JSON.parse(rawText) : {};
@@ -552,14 +746,32 @@ export function createApifyPlatformHooks(env = process.env, fetchImpl = globalTh
             Boolean(dataObj?.eventChargeLimitReached) ||
             limitReached ||
             (Number.isFinite(maxPayableEvents) && cumulativeChargedInAdapter >= maxPayableEvents);
-          const subsetIds = Array.isArray(dataObj?.chargedCreativeIds)
-            ? dataObj.chargedCreativeIds
-            : Array.isArray(receipt?.creativeIds)
-              ? receipt.creativeIds.slice(0, resolvedChargedCount)
-              : undefined;
+          let subsetIds;
+          if (Array.isArray(dataObj?.chargedCreativeIds)) {
+            const reqIds = Array.isArray(receipt?.creativeIds) ? receipt.creativeIds : null;
+            const uniqueValidIds = new Set(
+              dataObj.chargedCreativeIds.filter(
+                (id) => typeof id === 'string' && (!reqIds || reqIds.includes(id))
+              )
+            );
+            if (
+              dataObj.chargedCreativeIds.length !== resolvedChargedCount ||
+              uniqueValidIds.size !== resolvedChargedCount
+            ) {
+              throw new Error(
+                'Apify Pay-per-Event charge response contained invalid chargedCreativeIds'
+              );
+            }
+            subsetIds = Array.from(uniqueValidIds);
+          } else if (Array.isArray(receipt?.creativeIds)) {
+            subsetIds = receipt.creativeIds.slice(0, resolvedChargedCount);
+          }
           return {
             chargedCount: resolvedChargedCount,
             eventChargeLimitReached: resolvedLimitReached,
+            eventName: effectiveEventName,
+            unitPriceUsdc: resolvedUnitPriceUsdc,
+            idempotencyKey: effectiveIdempotencyKey,
             ...(subsetIds ? { chargedCreativeIds: subsetIds } : {}),
           };
         } finally {
@@ -704,7 +916,7 @@ export async function runGoogleAdsTransparencyActor(input = {}, hooks = {}) {
       'default_run'
   );
   const hasChargeHook = typeof hooks.chargeEvent === 'function';
-  const billingMode =
+  let billingMode =
     hasChargeHook || hooks.isAtHome === true ? 'APIFY_PAY_PER_EVENT' : 'LOCAL_UNBILLED';
 
   const maxRunDurationMs = Math.min(
@@ -1255,6 +1467,7 @@ export async function runGoogleAdsTransparencyActor(input = {}, hooks = {}) {
         advertiserId: targetItem.advertiserId,
         creativeId: targetItem.creativeId,
         includeAdCopy: Boolean(input?.includeAdCopy),
+        fallbackPreviewUrl: targetItem.previewUrl,
         fetchImpl: hooks.fetchImpl,
         nowFn: nowMs,
         sleepFn,
@@ -1282,6 +1495,14 @@ export async function runGoogleAdsTransparencyActor(input = {}, hooks = {}) {
             rateLimitedInEnrich = true;
           }
         }
+      } else if (detailRes.ok && detailRes.untrustedAdContent) {
+        targetItem.untrustedAdContent = detailRes.untrustedAdContent;
+        if (
+          detailRes.untrustedAdContent.extractionStatus === 'UPSTREAM_RATE_LIMITED' ||
+          detailRes.untrustedAdContent.contentJsFetchStatus === 'UPSTREAM_RATE_LIMITED'
+        ) {
+          rateLimitedInEnrich = true;
+        }
       }
     }
   }
@@ -1323,6 +1544,8 @@ export async function runGoogleAdsTransparencyActor(input = {}, hooks = {}) {
         chargedEventCount: hasChargeHook ? chargedSet.size : 0,
         durationMs,
         requestCount: Math.max(1, totalRpcRequests),
+        unitPriceUsdc: hooks?.unitPriceUsdc ?? ACTOR_PRICING_CONTRACT.priceUsdc,
+        actorStartFeeUsdc: hooks?.actorStartFeeUsdc,
       }),
     });
   }
@@ -1346,6 +1569,7 @@ export async function runGoogleAdsTransparencyActor(input = {}, hooks = {}) {
     }
   };
 
+  let lastResolvedUnitPriceUsdc = hooks?.unitPriceUsdc ?? ACTOR_PRICING_CONTRACT.priceUsdc;
   for (let offset = 0; offset < newBillableCandidates.length; offset += chunkSize) {
     const effectiveChunkDeadlineMs = hasChargeHook
       ? deadlineAtMs - step4ReserveMs
@@ -1446,6 +1670,28 @@ export async function runGoogleAdsTransparencyActor(input = {}, hooks = {}) {
     // Step 4.2: Strict ChargeResult validation (never fallback to ?? unchargedChunk.length)
     const chargedCount = chargeResult?.chargedCount;
     const eventChargeLimitReached = Boolean(chargeResult?.eventChargeLimitReached);
+    const resolvedReceiptEventName =
+      typeof chargeResult?.eventName === 'string' && chargeResult.eventName
+        ? chargeResult.eventName
+        : receipt.eventName;
+    const resolvedReceiptUnitPriceUsdc =
+      Number.isFinite(Number(chargeResult?.unitPriceUsdc)) && Number(chargeResult.unitPriceUsdc) > 0
+        ? Number(chargeResult.unitPriceUsdc)
+        : receipt.unitPriceUsdc;
+    lastResolvedUnitPriceUsdc = resolvedReceiptUnitPriceUsdc;
+    const resolvedReceiptIdempotencyKey =
+      typeof chargeResult?.idempotencyKey === 'string' && chargeResult.idempotencyKey
+        ? chargeResult.idempotencyKey
+        : receipt.idempotencyKey;
+    const buildFinalReceipt = (actualChargedCount, extra = {}) => ({
+      ...receipt,
+      idempotencyKey: resolvedReceiptIdempotencyKey,
+      eventName: resolvedReceiptEventName,
+      unitPriceUsdc: resolvedReceiptUnitPriceUsdc,
+      chunkAmountUsdc: Number((actualChargedCount * resolvedReceiptUnitPriceUsdc).toFixed(6)),
+      chargedCount: actualChargedCount,
+      ...extra,
+    });
 
     if (
       !chargeResult ||
@@ -1478,11 +1724,7 @@ export async function runGoogleAdsTransparencyActor(input = {}, hooks = {}) {
 
       const pushRes = await pushDataWithRetry(unchargedChunk);
       if (!pushRes.ok) {
-        chargeReceipts.push({
-          ...receipt,
-          chargedCount,
-          eventChargeLimitReached,
-        });
+        chargeReceipts.push(buildFinalReceipt(chargedCount, { eventChargeLimitReached }));
         finalOk = false;
         finalStatus = 'PARTIAL_BILLING_HALT';
         haltReason = `Dataset pushData failed after charge (paid items preserved in KVS checkpoint stagedItemsById): ${pushRes.error?.message || String(pushRes.error)}`;
@@ -1495,11 +1737,7 @@ export async function runGoogleAdsTransparencyActor(input = {}, hooks = {}) {
       deliveredCount = deliveredSet.size;
       await persistCheckpointPostCharge();
 
-      chargeReceipts.push({
-        ...receipt,
-        chargedCount,
-        eventChargeLimitReached,
-      });
+      chargeReceipts.push(buildFinalReceipt(chargedCount, { eventChargeLimitReached }));
 
       if (eventChargeLimitReached) {
         finalStatus = 'CHARGE_LIMIT_REACHED';
@@ -1507,12 +1745,32 @@ export async function runGoogleAdsTransparencyActor(input = {}, hooks = {}) {
       }
     } else if (chargedCount === 0) {
       inFlightSet = new Set();
+      if (chargeResult?.unbilledOwnerTestBypass === true) {
+        billingMode = 'UNBILLED_OWNER_TEST';
+        await persistCheckpointPostCharge();
+        const pushRes = await pushDataWithRetry(unchargedChunk);
+        if (!pushRes.ok) {
+          finalOk = false;
+          finalStatus = 'PARTIAL_BILLING_HALT';
+          haltReason = `Dataset pushData failed in UNBILLED_OWNER_TEST mode: ${pushRes.error?.message || String(pushRes.error)}`;
+          break;
+        }
+        for (const c of unchargedChunk) {
+          deliveredSet.add(c.creativeId);
+          newlyDeliveredItems.push(c);
+        }
+        deliveredCount = deliveredSet.size;
+        await persistCheckpointPostCharge();
+        chargeReceipts.push(
+          buildFinalReceipt(0, {
+            eventChargeLimitReached: false,
+            unbilledOwnerTestBypass: true,
+          })
+        );
+        continue;
+      }
       await persistCheckpointPostCharge();
-      chargeReceipts.push({
-        ...receipt,
-        chargedCount: 0,
-        eventChargeLimitReached,
-      });
+      chargeReceipts.push(buildFinalReceipt(0, { eventChargeLimitReached }));
       if (eventChargeLimitReached) {
         finalOk = true;
         finalStatus = 'CHARGE_LIMIT_REACHED';
@@ -1524,11 +1782,19 @@ export async function runGoogleAdsTransparencyActor(input = {}, hooks = {}) {
       break;
     } else {
       // Partial chunk charge (0 < chargedCount < unchargedChunk.length)
-      const explicitChargedIds = Array.isArray(chargeResult.chargedCreativeIds)
-        ? chargeResult.chargedCreativeIds.filter((id) => chunkIds.includes(id))
+      const hasExplicitIdsArray = Array.isArray(chargeResult.chargedCreativeIds);
+      const explicitChargedIds = hasExplicitIdsArray
+        ? Array.from(
+            new Set(chargeResult.chargedCreativeIds.filter((id) => chunkIds.includes(id)))
+          )
         : null;
+      const isValidExplicitChargedIds = Boolean(
+        explicitChargedIds &&
+          explicitChargedIds.length === chargedCount &&
+          chargeResult.chargedCreativeIds.length === chargedCount
+      );
 
-      if (explicitChargedIds && explicitChargedIds.length === chargedCount) {
+      if (isValidExplicitChargedIds) {
         for (const id of explicitChargedIds) {
           chargedSet.add(id);
         }
@@ -1539,12 +1805,12 @@ export async function runGoogleAdsTransparencyActor(input = {}, hooks = {}) {
         const paidSubset = unchargedChunk.filter((c) => explicitChargedIds.includes(c.creativeId));
         const pushRes = await pushDataWithRetry(paidSubset);
         if (!pushRes.ok) {
-          chargeReceipts.push({
-            ...receipt,
-            chargedCount,
-            chargedCreativeIds: explicitChargedIds,
-            eventChargeLimitReached,
-          });
+          chargeReceipts.push(
+            buildFinalReceipt(chargedCount, {
+              chargedCreativeIds: explicitChargedIds,
+              eventChargeLimitReached,
+            })
+          );
           finalOk = false;
           finalStatus = 'PARTIAL_BILLING_HALT';
           haltReason = `Dataset pushData failed after partial charge (paid items preserved in KVS checkpoint stagedItemsById): ${pushRes.error?.message || String(pushRes.error)}`;
@@ -1557,12 +1823,12 @@ export async function runGoogleAdsTransparencyActor(input = {}, hooks = {}) {
         deliveredCount = deliveredSet.size;
         await persistCheckpointPostCharge();
 
-        chargeReceipts.push({
-          ...receipt,
-          chargedCount,
-          chargedCreativeIds: explicitChargedIds,
-          eventChargeLimitReached,
-        });
+        chargeReceipts.push(
+          buildFinalReceipt(chargedCount, {
+            chargedCreativeIds: explicitChargedIds,
+            eventChargeLimitReached,
+          })
+        );
 
         finalOk = eventChargeLimitReached;
         finalStatus = eventChargeLimitReached ? 'CHARGE_LIMIT_REACHED' : 'PARTIAL_BILLING_HALT';
@@ -1570,7 +1836,7 @@ export async function runGoogleAdsTransparencyActor(input = {}, hooks = {}) {
           haltReason = `Partial chunk charge (${chargedCount}/${unchargedChunk.length}) without charge limit flag`;
         }
         break;
-      } else if (eventChargeLimitReached) {
+      } else if (!hasExplicitIdsArray && eventChargeLimitReached) {
         // Standard Apify SDK ChargeResult when hitting user's max charge ceiling:
         // Attribute charge deterministically to the ordered prefix `unchargedChunk.slice(0, chargedCount)`
         // so the customer receives every item they paid for, and leave the remaining tail uncharged.
@@ -1585,12 +1851,12 @@ export async function runGoogleAdsTransparencyActor(input = {}, hooks = {}) {
 
         const pushRes = await pushDataWithRetry(paidPrefix);
         if (!pushRes.ok) {
-          chargeReceipts.push({
-            ...receipt,
-            chargedCount,
-            chargedCreativeIds: paidPrefixIds,
-            eventChargeLimitReached: true,
-          });
+          chargeReceipts.push(
+            buildFinalReceipt(chargedCount, {
+              chargedCreativeIds: paidPrefixIds,
+              eventChargeLimitReached: true,
+            })
+          );
           finalOk = false;
           finalStatus = 'PARTIAL_BILLING_HALT';
           haltReason = `Dataset pushData failed after charge limit prefix (paid items preserved in KVS checkpoint stagedItemsById): ${pushRes.error?.message || String(pushRes.error)}`;
@@ -1603,12 +1869,12 @@ export async function runGoogleAdsTransparencyActor(input = {}, hooks = {}) {
         deliveredCount = deliveredSet.size;
         await persistCheckpointPostCharge();
 
-        chargeReceipts.push({
-          ...receipt,
-          chargedCount,
-          chargedCreativeIds: paidPrefixIds,
-          eventChargeLimitReached: true,
-        });
+        chargeReceipts.push(
+          buildFinalReceipt(chargedCount, {
+            chargedCreativeIds: paidPrefixIds,
+            eventChargeLimitReached: true,
+          })
+        );
 
         finalOk = true;
         finalStatus = 'CHARGE_LIMIT_REACHED';
@@ -1623,11 +1889,11 @@ export async function runGoogleAdsTransparencyActor(input = {}, hooks = {}) {
         chargedEventCount = chargedSet.size + chargedCount;
         await persistCheckpointPostCharge();
 
-        chargeReceipts.push({
-          ...receipt,
-          chargedCount,
-          eventChargeLimitReached: false,
-        });
+        chargeReceipts.push(
+          buildFinalReceipt(chargedCount, {
+            eventChargeLimitReached: false,
+          })
+        );
 
         finalOk = false;
         finalStatus = 'PARTIAL_BILLING_HALT';
@@ -1690,6 +1956,8 @@ export async function runGoogleAdsTransparencyActor(input = {}, hooks = {}) {
     chargedEventCount,
     durationMs,
     requestCount: Math.max(1, totalRpcRequests),
+    unitPriceUsdc: lastResolvedUnitPriceUsdc,
+    actorStartFeeUsdc: hooks?.actorStartFeeUsdc,
   });
 
   return finalizeActorReturn({

package/src/mcp_server.mjs

@@ -43,7 +43,7 @@ export const ENCODED_BRAND_ICON_DATA_URI = `data:image/svg+xml;utf8,${encodeURIC
 export const MCP_SERVER_INFO = Object.freeze({
   name: 'google-ads-transparency-mcp-actor',
   title: 'RevClamp AdPulse - For Google Ads Transparency Center (MCP & Apify Actor)',
-  version: '1.0.1',
+  version: '1.0.2',
   description:
     'Find verified Google Ads advertiser entities and extract active or historical ad creatives (Text, Image, Video), preview links, and run dates. Independent intelligence tool by RevClamp; not affiliated with or endorsed by Google LLC.',
   // Forward-compatible MCP Registry & Glama metadata extensions (ignored by older stdio clients)

package/src/rpc_client.mjs

@@ -1928,7 +1928,7 @@ export async function resolveAdvertiserEntities(options = {}) {
   const endpointUrl = options.endpointUrl || GOOGLE_ADS_RPC_ENDPOINTS.SearchSuggestions;
   const rpcRes = await executeGoogleAdsRpcPost(
     endpointUrl,
-    { '1': searchQueryStr, '2': 10, '3': 10 },
+    { '1': searchQueryStr, '2': 50, '3': 10 },
     options
   );
 
@@ -2291,8 +2291,20 @@ function isAllowedLandingHostname(hostname) {
   return true;
 }
 
+const VAST_CDATA_WRAPPER_SUFFIX_RE =
+  /(?:\]\]>|\]\]%3E|%5D%5D%3E|%5D%5D%253E|<\/[A-Za-z0-9_:-]+>|%3C\/[A-Za-z0-9_:-]+%3E|%3C%2F[A-Za-z0-9_:-]+%3E|%253C%2F[A-Za-z0-9_:-]+%253E).*$/i;
+
+function stripVastXmlCdataArtifacts(rawStr) {
+  if (typeof rawStr !== 'string' || !rawStr) return '';
+  return rawStr
+    .replace(/^(?:<!\[CDATA\[|%3C!%5BCDATA%5B)+/i, '')
+    .replace(VAST_CDATA_WRAPPER_SUFFIX_RE, '')
+    .replace(/[\]>]+$/, '')
+    .trim();
+}
+
 function normalizeCandidateLandingUrl(rawUrl) {
-  const cleaned = sanitizeUntrustedAdText(rawUrl, 2048);
+  const cleaned = stripVastXmlCdataArtifacts(sanitizeUntrustedAdText(rawUrl, 2048));
   if (!cleaned) return null;
   try {
     const parsed = new URL(cleaned);
@@ -2363,7 +2375,7 @@ function unwrapCandidateUrlOrAdUrlParam(rawUrl) {
   const adUrlMatch = decodedRaw.match(/[?&]adurl=([^"'\s&\\]+)/i);
   if (adUrlMatch && adUrlMatch[1]) {
     try {
-      const target = decodeURIComponent(adUrlMatch[1]);
+      const target = decodeURIComponent(stripVastXmlCdataArtifacts(adUrlMatch[1]));
       const normalizedTarget = normalizeCandidateLandingUrl(target);
       if (normalizedTarget) return normalizedTarget;
     } catch {
@@ -2583,7 +2595,9 @@ export function extractStaticAdCopyFromContentJs(rawJsText) {
       const adUrlParamMatch = surface.match(/[?&]adurl=(https?%3A%2F%2F[^"'\s&\\]+)/i);
       if (adUrlParamMatch && adUrlParamMatch[1]) {
         try {
-          landingPageUrl = normalizeCandidateLandingUrl(decodeURIComponent(adUrlParamMatch[1]));
+          landingPageUrl = normalizeCandidateLandingUrl(
+            decodeURIComponent(stripVastXmlCdataArtifacts(adUrlParamMatch[1]))
+          );
           if (landingPageUrl) break;
         } catch {
           landingPageUrl = null;
@@ -3558,17 +3572,33 @@ export async function getCreativeDetailsById(options = {}) {
     };
   }
 
+  const nowFn = typeof options.nowFn === 'function' ? options.nowFn : Date.now;
+  const fallbackPreviewUrl =
+    typeof options.fallbackPreviewUrl === 'string' && options.fallbackPreviewUrl.trim()
+      ? options.fallbackPreviewUrl.trim()
+      : null;
+
   if (canary.status === 'EMPTY_RESULT') {
+    let fallbackUntrustedAdContent = null;
+    if (
+      options.includeAdCopy === true &&
+      fallbackPreviewUrl &&
+      (!options.deadlineAtMs || nowFn() + 200 < options.deadlineAtMs)
+    ) {
+      fallbackUntrustedAdContent = await fetchAndExtractStaticAdCopy(fallbackPreviewUrl, options);
+    }
     return {
       ok: true,
       status: 'EMPTY_RESULT',
       detail: null,
+      ...(fallbackUntrustedAdContent ? { untrustedAdContent: fallbackUntrustedAdContent } : {}),
       rpcAttempts: rpcRes.attempts,
     };
   }
 
   const detailObj = rpcRes.data['1'];
   const { previewUrl, archiveImageUrls } = extractCreativeAssetUrls(detailObj?.['5'] ?? detailObj);
+  const effectivePreviewUrl = previewUrl || fallbackPreviewUrl;
   const rawRegions = Array.isArray(detailObj?.['17']) ? detailObj['17'] : [];
   const regionalPresence = rawRegions
     .filter((r) => r && typeof r === 'object')
@@ -3588,15 +3618,14 @@ export async function getCreativeDetailsById(options = {}) {
   let untrustedAdContent = extractStaticAdCopyFromContentJs(
     JSON.stringify(detailObj?.['5'] ?? detailObj)
   );
-  const nowFn = typeof options.nowFn === 'function' ? options.nowFn : Date.now;
   if (
     !untrustedAdContent.headline &&
     !untrustedAdContent.bodyText &&
     options.includeAdCopy === true &&
-    previewUrl &&
+    effectivePreviewUrl &&
     (!options.deadlineAtMs || nowFn() + 200 < options.deadlineAtMs)
   ) {
-    const fetchedCopy = await fetchAndExtractStaticAdCopy(previewUrl, options);
+    const fetchedCopy = await fetchAndExtractStaticAdCopy(effectivePreviewUrl, options);
     if (fetchedCopy.extractionStatus === 'EXTRACTED') {
       untrustedAdContent = {
         ...fetchedCopy,