mcp-scraper 0.2.0 → 0.2.1

package/dist/bin/paa-harvest.js

@@ -2,8 +2,8 @@
 import {
   browserServiceApiKey,
   harvest
-} from "../chunk-TM22BLWP.js";
-import "../chunk-ZMOWIBMK.js";
+} from "../chunk-MY3S7EX7.js";
+import "../chunk-M2S27J6Z.js";
 
 // src/cli.ts
 import { Command } from "commander";

package/dist/{chunk-GXBT5CDU.js → chunk-IQOCZGJJ.js}

@@ -1,7 +1,8 @@
 import {
   CaptchaError,
+  LocationMismatchError,
   RequestAbortedError
-} from "./chunk-ZMOWIBMK.js";
+} from "./chunk-M2S27J6Z.js";
 import {
   finishHarvestAttempt,
   startHarvestAttempt
@@ -207,6 +208,12 @@ function looksLikeTimeout(err, message) {
 function looksLikeCaptcha(message) {
   return /captcha|recaptcha|unusual traffic|google\.com\/sorry|blocked/i.test(message);
 }
+function looksLikeProxyTunnelFailure(message) {
+  return /ERR_TUNNEL_CONNECTION_FAILED|ERR_PROXY_CONNECTION_FAILED|ERR_SOCKS_CONNECTION_FAILED|tunnel connection failed|proxy connection failed|transport error: proxy/i.test(message);
+}
+function looksLikeProxyUnavailable(message) {
+  return /proxy unavailable|proxy_unavailable|connection_test_failed|did not return a proxy id|configured fallback/i.test(message);
+}
 function classifyHarvestProblem(err) {
   const message = errorMessage(err);
   if (err instanceof RequestAbortedError) {
@@ -229,6 +236,36 @@ function classifyHarvestProblem(err) {
       terminalStatus: "failed"
     };
   }
+  if (err instanceof LocationMismatchError) {
+    return {
+      error_code: "location_mismatch",
+      error_type: "location_mismatch",
+      message,
+      retryable: true,
+      httpStatus: 503,
+      terminalStatus: "failed"
+    };
+  }
+  if (looksLikeProxyTunnelFailure(message)) {
+    return {
+      error_code: "proxy_tunnel_failed",
+      error_type: "proxy_tunnel_failed",
+      message,
+      retryable: true,
+      httpStatus: 503,
+      terminalStatus: "failed"
+    };
+  }
+  if (looksLikeProxyUnavailable(message)) {
+    return {
+      error_code: "proxy_unavailable",
+      error_type: "proxy_unavailable",
+      message,
+      retryable: true,
+      httpStatus: 503,
+      terminalStatus: "failed"
+    };
+  }
   if (looksLikeTimeout(err, message)) {
     return {
       error_code: "harvest_timeout",
@@ -319,4 +356,4 @@ export {
   harvestProblemResponse,
   createHarvestAttemptRecorder
 };
-//# sourceMappingURL=chunk-GXBT5CDU.js.map
+//# sourceMappingURL=chunk-IQOCZGJJ.js.map

package/dist/chunk-IQOCZGJJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/api/rates.ts","../src/api/harvest-problems.ts","../src/api/harvest-attempt-events.ts"],"sourcesContent":["export const MC_COSTS = {\n  serp:              100,\n  paa:               100,\n  page_scrape:       100,\n  url_map:         2_000,\n  yt_channel:         50,\n  yt_transcription:  200,\n  fb_ad:              50,\n  maps_search:      2_000,\n  maps_place:      2_000,\n  maps_review:        50,\n  fb_search:          50,\n  fb_transcribe:      50,\n  browser_minute:  4_000,\n} as const\n\nexport type McCostKey = keyof typeof MC_COSTS\n\nexport const MC_PER_BROWSER_MS = MC_COSTS.browser_minute / 60_000\n\nexport function browserActiveCostMc(activeMs: number): number {\n  return Math.round(activeMs * MC_PER_BROWSER_MS)\n}\n\nexport const BROWSER_OPEN_MIN_BALANCE_MC = 1_000\n\nexport const MC_PER_CREDIT = 1_000\n\nexport const CREDIT_COST_CATALOG: Array<{\n  key: McCostKey\n  label: string\n  aliases: string[]\n  credits: number\n  unit: string\n  notes?: string\n}> = [\n  {\n    key: 'serp',\n    label: 'SERP search',\n    aliases: ['search_serp', 'serp', 'google search', 'organic results'],\n    credits: mcToCredits(MC_COSTS.serp),\n    unit: 'per search',\n    notes: 'Returns AI Overview, PAA snippet, videos, forums, and local pack.',\n  },\n  {\n    key: 'paa',\n    label: 'PAA harvest',\n    aliases: ['harvest_paa', 'paa', 'people also ask', 'questions'],\n    credits: mcToCredits(MC_COSTS.paa),\n    unit: 'per extracted question',\n    notes: 'Includes full SERP feature extraction. Billed on actual questions returned — no cap enforced.',\n  },\n  {\n    key: 'page_scrape',\n    label: 'Page crawl / extract',\n    aliases: ['extract_url', 'extract_site', 'page scrape', 'url scrape', 'single page', 'site crawl'],\n    credits: mcToCredits(MC_COSTS.page_scrape),\n    unit: 'per page',\n    notes: 'Applies to both single-URL extraction and per-page site crawls.',\n  },\n  {\n    key: 'url_map',\n    label: 'Site URL mapping',\n    aliases: ['map_site_urls', 'url map', 'site map', 'crawl urls'],\n    credits: mcToCredits(MC_COSTS.url_map),\n    unit: 'per mapping operation',\n    notes: 'Flat rate for the full /map-urls call regardless of URL count discovered.',\n  },\n  {\n    key: 'yt_channel',\n    label: 'YouTube search / channel harvest',\n    aliases: ['youtube_harvest', 'youtube search', 'youtube channel', 'yt_channel'],\n    credits: mcToCredits(MC_COSTS.yt_channel),\n    unit: 'per call',\n  },\n  {\n    key: 'yt_transcription',\n    label: 'YouTube transcription',\n    aliases: ['youtube_transcribe', 'youtube transcript', 'transcription', 'yt_transcription'],\n    credits: mcToCredits(MC_COSTS.yt_transcription),\n    unit: 'per minute',\n    notes: 'A 5-minute hold is taken, then reconciled to actual video duration.',\n  },\n  {\n    key: 'fb_ad',\n    label: 'Facebook search / ad lookup',\n    aliases: ['facebook_page_intel', 'facebook_ad_search', 'facebook_ad', 'facebook ads', 'fb ads'],\n    credits: mcToCredits(MC_COSTS.fb_ad),\n    unit: 'per call',\n  },\n  {\n    key: 'maps_search',\n    label: 'Maps business search',\n    aliases: ['maps_search', 'google maps search', 'gmb search', 'gbp search', 'business profiles'],\n    credits: mcToCredits(MC_COSTS.maps_search),\n    unit: 'per search',\n    notes: 'Returns up to 50 Google Maps business/profile candidates. Use maps_place_intel to hydrate selected businesses.',\n  },\n  {\n    key: 'maps_place',\n    label: 'Maps business lookup',\n    aliases: ['maps_place_intel', 'google maps', 'maps place', 'place intel'],\n    credits: mcToCredits(MC_COSTS.maps_place),\n    unit: 'per business',\n    notes: 'Base lookup. Reviews billed separately per card at maps_review rate.',\n  },\n  {\n    key: 'maps_review',\n    label: 'Maps review',\n    aliases: ['maps_reviews', 'google reviews', 'review cards', 'reviews'],\n    credits: mcToCredits(MC_COSTS.maps_review),\n    unit: 'per review card',\n    notes: 'Charged after extraction when includeReviews is true.',\n  },\n  {\n    key: 'fb_search',\n    label: 'Facebook ad library search',\n    aliases: ['facebook_search', 'fb_search', 'fb ad search'],\n    credits: mcToCredits(MC_COSTS.fb_search),\n    unit: 'per search',\n    notes: 'Browser automation to search Facebook Ads Library by keyword.',\n  },\n  {\n    key: 'fb_transcribe',\n    label: 'Facebook ad transcription',\n    aliases: ['facebook_transcribe', 'fb_transcribe', 'fb ad transcript'],\n    credits: mcToCredits(MC_COSTS.fb_transcribe),\n    unit: 'per call',\n    notes: 'Whisper transcription of Facebook ad video via fal.ai.',\n  },\n  {\n    key: 'browser_minute',\n    label: 'Interactive browser session',\n    aliases: ['browser_open', 'browser agent', 'browser_agent', 'live browser', 'browse', 'browser control', 'interactive browser'],\n    credits: mcToCredits(MC_COSTS.browser_minute),\n    unit: 'per minute of active time',\n    notes: 'Metered per second of active browser work (navigation, clicks, typing, screenshots). Idle and standby time are free. Billed against your balance as you act; close the session to stop the meter.',\n  },\n]\n\nexport const CONCURRENCY_PRICE_ID = 'price_1Ta1NRS8aAcsk3TGwsRnYbix'\n\nexport const FREE_SIGNUP_MC = 500_000\nexport const FREE_MONTHLY_REFRESH_MC = 250_000\n\nexport const BALANCE_PRICE_IDS: Record<string, number> = {\n  'price_1TZx6rS8aAcsk3TGNMc1Vgpo': 11_000_000,\n  'price_1TZx6sS8aAcsk3TGxgqB7khO': 27_500_000,\n  'price_1TZx6tS8aAcsk3TG8PnJqHlG': 60_500_000,\n  'price_1TZx6tS8aAcsk3TGNgRMpy0e': 121_000_000,\n}\n\nexport const BALANCE_PACK_LABELS: Record<string, string> = {\n  'price_1TZx6rS8aAcsk3TGNMc1Vgpo': '$10',\n  'price_1TZx6sS8aAcsk3TGxgqB7khO': '$25',\n  'price_1TZx6tS8aAcsk3TG8PnJqHlG': '$50',\n  'price_1TZx6tS8aAcsk3TGNgRMpy0e': '$100',\n}\n\nexport function mcToCredits(mc: number): number {\n  return mc / MC_PER_CREDIT\n}\n\nexport function insufficientBalanceResponse(balanceMc: number, requiredMc: number) {\n  const topupUrl = process.env.TOPUP_URL ?? 'https://mcpscraper.dev/billing'\n  const balanceCredits = mcToCredits(balanceMc)\n  const requiredCredits = mcToCredits(requiredMc)\n  return {\n    error: 'insufficient_balance',\n    error_code: 'insufficient_balance' as const,\n    message: `Insufficient credits. Balance: ${balanceCredits} credits. This call requires ${requiredCredits} credits. Top up at ${topupUrl}`,\n    balance_credits: balanceCredits,\n    required_credits: requiredCredits,\n    topup_url: topupUrl,\n  }\n}\n\nexport const LedgerOperation = {\n  TOPUP:                 'topup',\n  SIGNUP_GRANT:          'signup_grant',\n  MONTHLY_REFRESH:       'monthly_free_refresh',\n  PAA:                   'paa',\n  PAA_REFUND:            'paa_refund',\n  SERP:                  'serp',\n  REFUND:                'refund',\n  TRANSCRIPTION:         'transcription',\n  TRANSCRIPTION_HOLD:    'transcription_hold',\n  TRANSCRIPTION_REFUND:  'transcription_refund',\n  YT_CHANNEL:            'yt_channel',\n  FB_AD:                 'fb_ad',\n  MAPS_SEARCH:           'maps_search',\n  MAPS_PLACE:            'maps_place',\n  MAPS_REVIEW:           'maps_review',\n  MAPS_REVIEW_REFUND:    'maps_review_refund',\n  EXTRACT_SITE:          'extract_site',\n  EXTRACT_SITE_REFUND:   'extract_site_refund',\n  EXTRACT_URL:           'page_scrape',\n  URL_MAP:               'url_map',\n  EXTRACT_SITE_HOLD:     'extract_site_hold',\n  YT_CHANNEL_REFUND:     'yt_channel_refund',\n  FB_AD_REFUND:          'fb_ad_refund',\n  URL_MAP_REFUND:        'url_map_refund',\n  FB_SEARCH:             'fb_search',\n  FB_TRANSCRIBE:         'fb_transcribe',\n  FB_SEARCH_REFUND:      'fb_search_refund',\n  FB_TRANSCRIBE_REFUND:  'fb_transcribe_refund',\n  BROWSER_SESSION:       'browser_session',\n} as const\n\nexport type LedgerOperation = typeof LedgerOperation[keyof typeof LedgerOperation]\n","import { CaptchaError, LocationMismatchError, RequestAbortedError } from '../errors.js'\n\nexport type HarvestProblemCode =\n  | 'request_aborted'\n  | 'captcha_exhausted'\n  | 'location_mismatch'\n  | 'proxy_tunnel_failed'\n  | 'proxy_unavailable'\n  | 'harvest_timeout'\n  | 'extraction_failed'\n\nexport interface HarvestProblem {\n  error_code: HarvestProblemCode\n  error_type: string\n  message: string\n  retryable: boolean\n  httpStatus: number\n  terminalStatus: 'cancelled' | 'failed'\n}\n\nfunction errorMessage(err: unknown): string {\n  return err instanceof Error ? err.message : String(err)\n}\n\nfunction looksLikeTimeout(err: unknown, message: string): boolean {\n  if (err instanceof DOMException && (err.name === 'TimeoutError' || err.name === 'AbortError')) return true\n  return /timeout|timed out|Timeout \\d+ms exceeded|deadline/i.test(message)\n}\n\nfunction looksLikeCaptcha(message: string): boolean {\n  return /captcha|recaptcha|unusual traffic|google\\.com\\/sorry|blocked/i.test(message)\n}\n\nfunction looksLikeProxyTunnelFailure(message: string): boolean {\n  return /ERR_TUNNEL_CONNECTION_FAILED|ERR_PROXY_CONNECTION_FAILED|ERR_SOCKS_CONNECTION_FAILED|tunnel connection failed|proxy connection failed|transport error: proxy/i.test(message)\n}\n\nfunction looksLikeProxyUnavailable(message: string): boolean {\n  return /proxy unavailable|proxy_unavailable|connection_test_failed|did not return a proxy id|configured fallback/i.test(message)\n}\n\nexport function classifyHarvestProblem(err: unknown): HarvestProblem {\n  const message = errorMessage(err)\n\n  if (err instanceof RequestAbortedError) {\n    return {\n      error_code: 'request_aborted',\n      error_type: 'request_aborted',\n      message,\n      retryable: true,\n      httpStatus: 408,\n      terminalStatus: 'cancelled',\n    }\n  }\n\n  if (err instanceof CaptchaError || looksLikeCaptcha(message)) {\n    return {\n      error_code: 'captcha_exhausted',\n      error_type: 'captcha',\n      message,\n      retryable: true,\n      httpStatus: 503,\n      terminalStatus: 'failed',\n    }\n  }\n\n  if (err instanceof LocationMismatchError) {\n    return {\n      error_code: 'location_mismatch',\n      error_type: 'location_mismatch',\n      message,\n      retryable: true,\n      httpStatus: 503,\n      terminalStatus: 'failed',\n    }\n  }\n\n  if (looksLikeProxyTunnelFailure(message)) {\n    return {\n      error_code: 'proxy_tunnel_failed',\n      error_type: 'proxy_tunnel_failed',\n      message,\n      retryable: true,\n      httpStatus: 503,\n      terminalStatus: 'failed',\n    }\n  }\n\n  if (looksLikeProxyUnavailable(message)) {\n    return {\n      error_code: 'proxy_unavailable',\n      error_type: 'proxy_unavailable',\n      message,\n      retryable: true,\n      httpStatus: 503,\n      terminalStatus: 'failed',\n    }\n  }\n\n  if (looksLikeTimeout(err, message)) {\n    return {\n      error_code: 'harvest_timeout',\n      error_type: 'timeout',\n      message,\n      retryable: true,\n      httpStatus: 504,\n      terminalStatus: 'failed',\n    }\n  }\n\n  return {\n    error_code: 'extraction_failed',\n    error_type: 'extraction',\n    message,\n    retryable: false,\n    httpStatus: 500,\n    terminalStatus: 'failed',\n  }\n}\n\nexport function serializeHarvestProblem(problem: HarvestProblem): string {\n  return JSON.stringify({\n    error_code: problem.error_code,\n    error_type: problem.error_type,\n    message: problem.message,\n    retryable: problem.retryable,\n  })\n}\n\nexport function harvestProblemResponse(problem: HarvestProblem): {\n  error: string\n  error_code: HarvestProblemCode\n  error_type: string\n  retryable: boolean\n} {\n  return {\n    error: problem.message,\n    error_code: problem.error_code,\n    error_type: problem.error_type,\n    retryable: problem.retryable,\n  }\n}\n","import type { HarvestAttemptLogEvent } from '../harvest.js'\nimport { finishHarvestAttempt, startHarvestAttempt } from './db.js'\n\nexport function createHarvestAttemptRecorder(jobId: string, userId: number | bigint) {\n  return async (event: HarvestAttemptLogEvent): Promise<void> => {\n    if (event.type === 'started') {\n      await startHarvestAttempt({\n        jobId,\n        userId,\n        attemptNumber: event.attemptNumber,\n        maxAttempts: event.maxAttempts,\n        query: event.query,\n        location: event.location,\n        maxQuestions: event.maxQuestions,\n        startedAt: event.startedAt,\n      })\n      return\n    }\n\n    await finishHarvestAttempt({\n      jobId,\n      attemptNumber: event.attemptNumber,\n      outcome: event.outcome,\n      kernelSessionId: event.kernelSessionId,\n      questionCount: event.questionCount,\n      durationMs: event.durationMs,\n      error: event.error,\n      willRetry: event.willRetry,\n      kernelDeleteStarted: event.cleanup.kernelDeleteStarted,\n      kernelDeleteSucceeded: event.cleanup.kernelDeleteSucceeded,\n      kernelDeleteError: event.cleanup.kernelDeleteError,\n      browserCloseSucceeded: event.cleanup.browserCloseSucceeded,\n      browserCloseError: event.cleanup.browserCloseError,\n      debug: event.debug,\n      completedAt: event.completedAt,\n    })\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-ZMOWIBMK.js → chunk-M2S27J6Z.js}

@@ -25,12 +25,19 @@ var RequestAbortedError = class extends Error {
     super(message);
   }
 };
+var LocationMismatchError = class extends Error {
+  name = "LocationMismatchError";
+  constructor(message = "Google returned results for a different location than requested") {
+    super(message);
+  }
+};
 
 export {
   RECAPTCHA_INSTRUCTIONS,
   sanitizeVendorName,
   CaptchaError,
   ExtractionError,
-  RequestAbortedError
+  RequestAbortedError,
+  LocationMismatchError
 };
-//# sourceMappingURL=chunk-ZMOWIBMK.js.map
+//# sourceMappingURL=chunk-M2S27J6Z.js.map

package/dist/{chunk-ZMOWIBMK.js.map → chunk-M2S27J6Z.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/errors.ts"],"sourcesContent":["export const RECAPTCHA_INSTRUCTIONS = 'Google returned a CAPTCHA. Run with --headless=false to re-warm the browser profile, then retry.'\n\nexport function sanitizeVendorName(message: string): string {\n  return message\n    .replace(/kernel\\.sh\\s+sessions?/gi, 'sessions')\n    .replace(/kernel\\.sh\\s+session/gi, 'this session')\n    .replace(/kernel\\.sh/gi, 'the service')\n    .replace(/kernel\\s+sessions?/gi, 'sessions')\n    .replace(/kernel\\s+session/gi, 'this session')\n    .replace(/\\bkernel\\b/gi, 'the service')\n    .replace(/  +/g, ' ')\n    .trim()\n}\n\nexport class CaptchaError extends Error {\n  readonly name = 'CaptchaError'\n  constructor(public readonly instructions: string) {\n    super(`CAPTCHA detected. ${instructions}`)\n  }\n}\n\nexport class ExtractionError extends Error {\n  readonly name = 'ExtractionError'\n  constructor(message: string, public readonly cause?: unknown) {\n    super(message)\n  }\n}\n\nexport class RequestAbortedError extends Error {\n  readonly name = 'RequestAbortedError'\n  constructor(message = 'Request aborted before harvest completed') {\n    super(message)\n  }\n}\n"],"mappings":";AAAO,IAAM,yBAAyB;AAE/B,SAAS,mBAAmB,SAAyB;AAC1D,SAAO,QACJ,QAAQ,4BAA4B,UAAU,EAC9C,QAAQ,0BAA0B,cAAc,EAChD,QAAQ,gBAAgB,aAAa,EACrC,QAAQ,wBAAwB,UAAU,EAC1C,QAAQ,sBAAsB,cAAc,EAC5C,QAAQ,gBAAgB,aAAa,EACrC,QAAQ,QAAQ,GAAG,EACnB,KAAK;AACV;AAEO,IAAM,eAAN,cAA2B,MAAM;AAAA,EAEtC,YAA4B,cAAsB;AAChD,UAAM,qBAAqB,YAAY,EAAE;AADf;AAAA,EAE5B;AAAA,EAF4B;AAAA,EADnB,OAAO;AAIlB;AAEO,IAAM,kBAAN,cAA8B,MAAM;AAAA,EAEzC,YAAY,SAAiC,OAAiB;AAC5D,UAAM,OAAO;AAD8B;AAAA,EAE7C;AAAA,EAF6C;AAAA,EADpC,OAAO;AAIlB;AAEO,IAAM,sBAAN,cAAkC,MAAM;AAAA,EACpC,OAAO;AAAA,EAChB,YAAY,UAAU,4CAA4C;AAChE,UAAM,OAAO;AAAA,EACf;AACF;","names":[]}
+{"version":3,"sources":["../src/errors.ts"],"sourcesContent":["export const RECAPTCHA_INSTRUCTIONS = 'Google returned a CAPTCHA. Run with --headless=false to re-warm the browser profile, then retry.'\n\nexport function sanitizeVendorName(message: string): string {\n  return message\n    .replace(/kernel\\.sh\\s+sessions?/gi, 'sessions')\n    .replace(/kernel\\.sh\\s+session/gi, 'this session')\n    .replace(/kernel\\.sh/gi, 'the service')\n    .replace(/kernel\\s+sessions?/gi, 'sessions')\n    .replace(/kernel\\s+session/gi, 'this session')\n    .replace(/\\bkernel\\b/gi, 'the service')\n    .replace(/  +/g, ' ')\n    .trim()\n}\n\nexport class CaptchaError extends Error {\n  readonly name = 'CaptchaError'\n  constructor(public readonly instructions: string) {\n    super(`CAPTCHA detected. ${instructions}`)\n  }\n}\n\nexport class ExtractionError extends Error {\n  readonly name = 'ExtractionError'\n  constructor(message: string, public readonly cause?: unknown) {\n    super(message)\n  }\n}\n\nexport class RequestAbortedError extends Error {\n  readonly name = 'RequestAbortedError'\n  constructor(message = 'Request aborted before harvest completed') {\n    super(message)\n  }\n}\n\nexport class LocationMismatchError extends Error {\n  readonly name = 'LocationMismatchError'\n  constructor(message = 'Google returned results for a different location than requested') {\n    super(message)\n  }\n}\n"],"mappings":";AAAO,IAAM,yBAAyB;AAE/B,SAAS,mBAAmB,SAAyB;AAC1D,SAAO,QACJ,QAAQ,4BAA4B,UAAU,EAC9C,QAAQ,0BAA0B,cAAc,EAChD,QAAQ,gBAAgB,aAAa,EACrC,QAAQ,wBAAwB,UAAU,EAC1C,QAAQ,sBAAsB,cAAc,EAC5C,QAAQ,gBAAgB,aAAa,EACrC,QAAQ,QAAQ,GAAG,EACnB,KAAK;AACV;AAEO,IAAM,eAAN,cAA2B,MAAM;AAAA,EAEtC,YAA4B,cAAsB;AAChD,UAAM,qBAAqB,YAAY,EAAE;AADf;AAAA,EAE5B;AAAA,EAF4B;AAAA,EADnB,OAAO;AAIlB;AAEO,IAAM,kBAAN,cAA8B,MAAM;AAAA,EAEzC,YAAY,SAAiC,OAAiB;AAC5D,UAAM,OAAO;AAD8B;AAAA,EAE7C;AAAA,EAF6C;AAAA,EADpC,OAAO;AAIlB;AAEO,IAAM,sBAAN,cAAkC,MAAM;AAAA,EACpC,OAAO;AAAA,EAChB,YAAY,UAAU,4CAA4C;AAChE,UAAM,OAAO;AAAA,EACf;AACF;AAEO,IAAM,wBAAN,cAAoC,MAAM;AAAA,EACtC,OAAO;AAAA,EAChB,YAAY,UAAU,mEAAmE;AACvF,UAAM,OAAO;AAAA,EACf;AACF;","names":[]}

package/dist/{chunk-TM22BLWP.js → chunk-MY3S7EX7.js}

@@ -1,10 +1,11 @@
 import {
   CaptchaError,
   ExtractionError,
+  LocationMismatchError,
   RECAPTCHA_INSTRUCTIONS,
   RequestAbortedError,
   sanitizeVendorName
-} from "./chunk-ZMOWIBMK.js";
+} from "./chunk-M2S27J6Z.js";
 
 // src/lib/browser-service-env.ts
 function browserServiceApiKey() {
@@ -57,8 +58,12 @@ var MapsSearchOptionsSchema = z.object({
   gl: z.string().length(2).default("us"),
   hl: z.string().length(2).default("en"),
   maxResults: z.number().int().min(1).max(50).default(10),
+  proxyMode: z.enum(["location", "configured", "none"]).default("location"),
+  proxyZip: z.string().regex(/^\d{5}$/).optional(),
+  debug: z.boolean().default(false),
   kernelApiKey: z.string().optional(),
   kernelProxyId: z.string().optional(),
+  kernelProxyResolution: z.unknown().optional(),
   headless: z.boolean().default(true)
 });
 var RawPAAItemSchema = z.object({
@@ -2232,16 +2237,18 @@ var US_CITY_CENTER_ZIPS = {
 function proxyIdSuffix2(proxyId) {
   return proxyId ? proxyId.slice(-6) : null;
 }
-function resolution(source, proxyMode, proxyId, target, error) {
+function resolution(source, proxyMode, proxyId, target, error, disposable = false) {
   return {
     kernelProxyId: proxyId,
+    ...disposable && proxyId ? { disposableProxyId: proxyId } : {},
     resolution: {
       source,
       proxyMode,
       proxyIdPresent: Boolean(proxyId),
       proxyIdSuffix: proxyIdSuffix2(proxyId),
       target,
-      error
+      error,
+      disposable
     }
   };
 }
@@ -2271,6 +2278,10 @@ function kernelCityIdentifierCandidates(city) {
 function proxyName(country, state, city) {
   return city ? `mcp-serp-residential-${country.toLowerCase()}-${state.toLowerCase()}-${city}` : `mcp-serp-residential-${country.toLowerCase()}-${state.toLowerCase()}`;
 }
+function freshProxyName(baseName, attemptIndex) {
+  const stamp = `${Date.now()}-${attemptIndex ?? 0}-${Math.random().toString(36).slice(2, 8)}`;
+  return `${baseName}-fresh-${stamp}`;
+}
 function zipProxyName(zip) {
   return `mcp-serp-residential-us-zip-${zip}`;
 }
@@ -2340,6 +2351,12 @@ function zipTarget(target, zip) {
     }
   };
 }
+function withProxyName(target, name) {
+  return {
+    ...target,
+    proxyName: name
+  };
+}
 function configMatches(config, target, city) {
   if (target.level === "zip") {
     return config?.country?.toUpperCase() === target.country && config?.zip === target.zip;
@@ -2378,6 +2395,55 @@ function escalatedTargetLevel(target, attemptIndex) {
 function errorText2(err) {
   return err instanceof Error ? err.message : String(err);
 }
+function freshTargetCandidates(target, explicitZip, attemptIndex) {
+  const out = [];
+  const zip = knownZipFor(target, explicitZip);
+  if (zip) {
+    const targetZip = zipTarget(target, zip);
+    out.push(withProxyName(targetZip, freshProxyName(targetZip.proxyName, attemptIndex)));
+  }
+  for (const city of target.cityCandidates) {
+    const cityTarget = {
+      ...target,
+      level: "city",
+      city,
+      proxyName: proxyName(target.country, target.state, city),
+      config: {
+        country: target.country,
+        state: target.state,
+        city
+      }
+    };
+    out.push(withProxyName(cityTarget, freshProxyName(cityTarget.proxyName, attemptIndex)));
+  }
+  const fallbackTarget = stateTarget(target);
+  out.push(withProxyName(fallbackTarget, freshProxyName(fallbackTarget.proxyName, attemptIndex)));
+  return out;
+}
+async function createFreshLocationProxy(kernel, options, target) {
+  const createErrors = [];
+  for (const candidate of freshTargetCandidates(target, options.proxyZip, options.attemptIndex)) {
+    try {
+      const created = await kernel.proxies.create({
+        type: "residential",
+        name: candidate.proxyName,
+        config: candidate.level === "zip" ? { country: candidate.country, zip: candidate.zip } : candidate.config
+      });
+      if (created.id) {
+        return resolution("location_created", options.proxyMode, created.id, candidate, null, true);
+      }
+      createErrors.push(`${candidate.proxyName}: Kernel did not return a proxy id`);
+    } catch (err) {
+      createErrors.push(`${candidate.proxyName}: ${errorText2(err)}`);
+    }
+  }
+  return resolution("configured_fallback", options.proxyMode, options.configuredKernelProxyId, target, createErrors.join(" | "));
+}
+async function deleteKernelProxyId(kernelApiKey, proxyId) {
+  if (!kernelApiKey || !proxyId) return;
+  const kernel = new Kernel2({ apiKey: kernelApiKey });
+  await kernel.proxies.delete(proxyId);
+}
 async function resolveKernelProxyId(options) {
   if (options.proxyMode === "none") {
     return resolution("disabled", options.proxyMode, void 0, null, null);
@@ -2392,6 +2458,9 @@ async function resolveKernelProxyId(options) {
   const kernel = new Kernel2({ apiKey: options.kernelApiKey });
   try {
     const attemptIndex = options.attemptIndex ?? 0;
+    if (options.fresh) {
+      return await createFreshLocationProxy(kernel, options, target);
+    }
     if (attemptIndex >= 1) {
       const escalatedTarget = escalatedTargetLevel(target, attemptIndex);
       const createErrors2 = [];
@@ -2495,6 +2564,7 @@ async function resolveKernelProxyId(options) {
 
 // src/harvest.ts
 var MAX_ATTEMPTS = 3;
+var LOCATION_PROXY_MAX_ATTEMPTS = 5;
 function abortReason(signal) {
   if (signal.reason instanceof DOMException && signal.reason.name === "TimeoutError") return signal.reason;
   return new RequestAbortedError();
@@ -2524,9 +2594,12 @@ async function emitAttemptEvent(sink, event) {
 }
 function classifyAttemptError(err) {
   if (err instanceof CaptchaError) return "captcha";
+  if (err instanceof LocationMismatchError) return "location_mismatch";
   if (err instanceof RequestAbortedError) return "request_aborted";
   if (err instanceof DOMException && (err.name === "TimeoutError" || err.name === "AbortError")) return "timeout";
   const message = err instanceof Error ? err.message : String(err);
+  if (looksLikeProxyTunnelFailure(message)) return "proxy_tunnel_failed";
+  if (looksLikeProxyUnavailable(message)) return "proxy_unavailable";
   return /timeout|timed out|Timeout \d+ms exceeded|deadline/i.test(message) ? "timeout" : "error";
 }
 function classifyAttemptResult(result) {
@@ -2535,6 +2608,49 @@ function classifyAttemptResult(result) {
 function errorMessage(err) {
   return err instanceof Error ? err.message : String(err);
 }
+function maxAttemptsForProxyMode(proxyMode) {
+  return proxyMode === "location" ? LOCATION_PROXY_MAX_ATTEMPTS : MAX_ATTEMPTS;
+}
+function looksLikeProxyTunnelFailure(message) {
+  return /ERR_TUNNEL_CONNECTION_FAILED|ERR_PROXY_CONNECTION_FAILED|ERR_SOCKS_CONNECTION_FAILED|tunnel connection failed|proxy connection failed|transport error: proxy/i.test(message);
+}
+function looksLikeProxyUnavailable(message) {
+  return /proxy unavailable|proxy_unavailable|connection_test_failed|did not return a proxy id|configured fallback/i.test(message);
+}
+function retryableLocationProxyError(outcome) {
+  return outcome === "captcha" || outcome === "proxy_tunnel_failed" || outcome === "proxy_unavailable";
+}
+function locationMismatchMessage(result) {
+  const evidence = result.diagnostics.debug?.locationEvidence;
+  const expected = evidence?.expected?.canonicalLocation ?? result.location ?? "requested location";
+  const candidates = evidence?.candidates.slice(0, 3).map((candidate) => `${candidate.city}, ${candidate.regionCode}`).join("; ");
+  return candidates ? `Google returned results for ${candidates}, not ${expected}` : `Google returned results for a different location than ${expected}`;
+}
+function shouldRetryLocationMismatch(result, proxyMode) {
+  return proxyMode === "location" && result.diagnostics.debug?.locationEvidence?.status === "mismatch";
+}
+function stripInternalDebug(result, keepDebug) {
+  if (keepDebug || !result.diagnostics.debug) return result;
+  const diagnostics = { ...result.diagnostics };
+  delete diagnostics.debug;
+  return { ...result, diagnostics };
+}
+async function cleanupDisposableProxy(kernelApiKey, proxyId) {
+  if (!kernelApiKey || !proxyId) return;
+  try {
+    await deleteKernelProxyId(kernelApiKey, proxyId);
+    console.info(JSON.stringify({
+      event: "kernel_proxy_deleted",
+      proxy_id_suffix: proxyId.slice(-6)
+    }));
+  } catch (err) {
+    console.warn(JSON.stringify({
+      event: "kernel_proxy_delete_failed",
+      proxy_id_suffix: proxyId.slice(-6),
+      message: errorMessage(err)
+    }));
+  }
+}
 async function extractOnce(options, signal) {
   const driver = new BrowserDriver();
   const reporter = new ProgressReporter();
@@ -2602,26 +2718,35 @@ async function harvest(rawOptions) {
     proxyZip: typeof raw.proxyZip === "string" ? raw.proxyZip : void 0,
     gl: typeof raw.gl === "string" ? raw.gl : "us"
   };
+  const requestedDebug = typeof raw.debug === "boolean" ? raw.debug : false;
+  const needsLocationEvidence = proxyMode === "location" && Boolean(proxyOpts.location);
+  const maxAttempts = maxAttemptsForProxyMode(proxyMode);
   const serializer = new OutputSerializer();
-  for (let i = 0; i < MAX_ATTEMPTS; i++) {
+  let lastError = null;
+  for (let i = 0; i < maxAttempts; i++) {
     const attemptNumber = i + 1;
     const startedAtMs = Date.now();
     try {
       if (signal?.aborted) throw abortReason(signal);
-      const resolution2 = await resolveKernelProxyId({ ...proxyOpts, attemptIndex: i });
+      const resolution2 = await resolveKernelProxyId({
+        ...proxyOpts,
+        attemptIndex: i,
+        fresh: proxyMode === "location"
+      });
       const mergedAttempt = {
         ...raw,
         kernelApiKey,
         kernelProxyId: resolution2.kernelProxyId,
         kernelProxyResolution: resolution2.resolution,
-        proxyMode
+        proxyMode,
+        debug: requestedDebug || needsLocationEvidence
       };
       if (proxyMode === "none") mergedAttempt.kernelProxyId = void 0;
       const attemptOptions = HarvestOptionsSchema.parse(mergedAttempt);
       await emitAttemptEvent(onAttemptEvent, {
         type: "started",
         attemptNumber,
-        maxAttempts: MAX_ATTEMPTS,
+        maxAttempts,
         query: attemptOptions.query,
         location: attemptOptions.location ?? null,
         maxQuestions: attemptOptions.maxQuestions,
@@ -2630,7 +2755,7 @@ async function harvest(rawOptions) {
       console.info(JSON.stringify({
         event: "harvest_attempt_started",
         attempt_number: attemptNumber,
-        max_attempts: MAX_ATTEMPTS,
+        max_attempts: maxAttempts,
         query: attemptOptions.query,
         location: attemptOptions.location ?? null,
         max_questions: attemptOptions.maxQuestions
@@ -2638,57 +2763,84 @@ async function harvest(rawOptions) {
       const attempt = await extractOnce(attemptOptions, signal);
       if (attempt.error) {
         const err = attempt.error;
-        if (err instanceof CaptchaError) {
-          const willRetry = i < MAX_ATTEMPTS - 1;
+        const outcome = classifyAttemptError(err);
+        const willRetry = i < maxAttempts - 1 && (outcome === "captcha" || proxyMode === "location" && retryableLocationProxyError(outcome));
+        if (outcome === "captcha") {
           console.warn(JSON.stringify({
             event: "harvest_attempt_captcha",
             attempt_number: attemptNumber,
-            max_attempts: MAX_ATTEMPTS,
-            message: err.message,
+            max_attempts: maxAttempts,
+            message: errorMessage(err),
+            will_retry: willRetry
+          }));
+        } else if (willRetry) {
+          console.warn(JSON.stringify({
+            event: "harvest_attempt_proxy_retry",
+            attempt_number: attemptNumber,
+            max_attempts: maxAttempts,
+            outcome,
+            message: errorMessage(err),
             will_retry: willRetry
           }));
-          await emitAttemptEvent(onAttemptEvent, {
-            type: "finished",
-            attemptNumber,
-            maxAttempts: MAX_ATTEMPTS,
-            outcome: "captcha",
-            kernelSessionId: attempt.cleanup.kernelSessionId,
-            questionCount: 0,
-            durationMs: Date.now() - startedAtMs,
-            error: err.message,
-            willRetry,
-            cleanup: attempt.cleanup,
-            debug: attempt.debug,
-            completedAt: (/* @__PURE__ */ new Date()).toISOString()
-          });
-          if (willRetry) continue;
-          break;
         }
         await emitAttemptEvent(onAttemptEvent, {
           type: "finished",
           attemptNumber,
-          maxAttempts: MAX_ATTEMPTS,
-          outcome: classifyAttemptError(err),
+          maxAttempts,
+          outcome,
           kernelSessionId: attempt.cleanup.kernelSessionId,
           questionCount: 0,
           durationMs: Date.now() - startedAtMs,
           error: errorMessage(err),
-          willRetry: false,
+          willRetry,
           cleanup: attempt.cleanup,
           debug: attempt.debug,
           completedAt: (/* @__PURE__ */ new Date()).toISOString()
         });
-        throw err;
+        await cleanupDisposableProxy(kernelApiKey, resolution2.disposableProxyId);
+        lastError = err;
+        if (willRetry) continue;
+        break;
       }
       const result = attempt.result;
       if (!result) throw new Error("Harvest attempt completed without a result");
+      if (shouldRetryLocationMismatch(result, proxyMode)) {
+        const err = new LocationMismatchError(locationMismatchMessage(result));
+        const willRetry = i < maxAttempts - 1;
+        console.warn(JSON.stringify({
+          event: "harvest_attempt_location_mismatch",
+          attempt_number: attemptNumber,
+          max_attempts: maxAttempts,
+          message: err.message,
+          will_retry: willRetry
+        }));
+        await emitAttemptEvent(onAttemptEvent, {
+          type: "finished",
+          attemptNumber,
+          maxAttempts,
+          outcome: "location_mismatch",
+          kernelSessionId: attempt.cleanup.kernelSessionId,
+          questionCount: result.totalQuestions,
+          durationMs: Date.now() - startedAtMs,
+          error: err.message,
+          willRetry,
+          cleanup: attempt.cleanup,
+          debug: attempt.debug,
+          completedAt: (/* @__PURE__ */ new Date()).toISOString()
+        });
+        await cleanupDisposableProxy(kernelApiKey, resolution2.disposableProxyId);
+        lastError = err;
+        if (willRetry) continue;
+        break;
+      }
+      const finalResult = stripInternalDebug(result, requestedDebug);
       await emitAttemptEvent(onAttemptEvent, {
         type: "finished",
         attemptNumber,
-        maxAttempts: MAX_ATTEMPTS,
-        outcome: classifyAttemptResult(result),
+        maxAttempts,
+        outcome: classifyAttemptResult(finalResult),
         kernelSessionId: attempt.cleanup.kernelSessionId,
-        questionCount: result.totalQuestions,
+        questionCount: finalResult.totalQuestions,
         durationMs: Date.now() - startedAtMs,
         error: null,
         willRetry: false,
@@ -2696,64 +2848,52 @@ async function harvest(rawOptions) {
         debug: attempt.debug,
         completedAt: (/* @__PURE__ */ new Date()).toISOString()
       });
+      await cleanupDisposableProxy(kernelApiKey, resolution2.disposableProxyId);
       if (attemptOptions.format === "json" || attemptOptions.format === "both") {
-        await serializer.writeJSON(result, attemptOptions.outputDir);
+        await serializer.writeJSON(finalResult, attemptOptions.outputDir);
       }
       if (attemptOptions.format === "csv" || attemptOptions.format === "both") {
         await Promise.all([
-          serializer.writeCSV(result.flat, attemptOptions.outputDir),
-          result.videos.length > 0 ? serializer.writeVideoCSV(result.videos, result.seed, attemptOptions.outputDir) : Promise.resolve(""),
-          result.forums.length > 0 ? serializer.writeForumCSV(result.forums, result.seed, attemptOptions.outputDir) : Promise.resolve(""),
-          result.aiOverview.detected ? serializer.writeAIOverviewCSV(result.aiOverview.citations, result.aiOverview.text, result.seed, attemptOptions.outputDir) : Promise.resolve(""),
-          result.aiMode.detected ? serializer.writeAIModeCSV(result.aiMode.citations, result.aiMode.text, result.seed, attemptOptions.outputDir) : Promise.resolve(""),
-          result.whatPeopleSaying.length > 0 ? serializer.writeWhatPeopleSayingCSV(result.whatPeopleSaying, result.seed, attemptOptions.outputDir) : Promise.resolve("")
+          serializer.writeCSV(finalResult.flat, attemptOptions.outputDir),
+          finalResult.videos.length > 0 ? serializer.writeVideoCSV(finalResult.videos, finalResult.seed, attemptOptions.outputDir) : Promise.resolve(""),
+          finalResult.forums.length > 0 ? serializer.writeForumCSV(finalResult.forums, finalResult.seed, attemptOptions.outputDir) : Promise.resolve(""),
+          finalResult.aiOverview.detected ? serializer.writeAIOverviewCSV(finalResult.aiOverview.citations, finalResult.aiOverview.text, finalResult.seed, attemptOptions.outputDir) : Promise.resolve(""),
+          finalResult.aiMode.detected ? serializer.writeAIModeCSV(finalResult.aiMode.citations, finalResult.aiMode.text, finalResult.seed, attemptOptions.outputDir) : Promise.resolve(""),
+          finalResult.whatPeopleSaying.length > 0 ? serializer.writeWhatPeopleSayingCSV(finalResult.whatPeopleSaying, finalResult.seed, attemptOptions.outputDir) : Promise.resolve("")
         ]);
       }
-      return result;
+      return finalResult;
     } catch (err) {
-      if (err instanceof CaptchaError) {
-        const willRetry = i < MAX_ATTEMPTS - 1;
+      const outcome = classifyAttemptError(err);
+      const willRetry = i < maxAttempts - 1 && (outcome === "captcha" || proxyMode === "location" && retryableLocationProxyError(outcome));
+      if (outcome === "captcha") {
         console.warn(JSON.stringify({
           event: "harvest_attempt_captcha",
           attempt_number: attemptNumber,
-          max_attempts: MAX_ATTEMPTS,
-          message: err.message,
+          max_attempts: maxAttempts,
+          message: errorMessage(err),
+          will_retry: willRetry
+        }));
+      } else if (willRetry) {
+        console.warn(JSON.stringify({
+          event: "harvest_attempt_proxy_retry",
+          attempt_number: attemptNumber,
+          max_attempts: maxAttempts,
+          outcome,
+          message: errorMessage(err),
           will_retry: willRetry
         }));
-        await emitAttemptEvent(onAttemptEvent, {
-          type: "finished",
-          attemptNumber,
-          maxAttempts: MAX_ATTEMPTS,
-          outcome: "captcha",
-          kernelSessionId: null,
-          questionCount: 0,
-          durationMs: Date.now() - startedAtMs,
-          error: err.message,
-          willRetry,
-          cleanup: {
-            kernelSessionId: null,
-            kernelDeleteStarted: false,
-            kernelDeleteSucceeded: null,
-            kernelDeleteError: null,
-            browserCloseSucceeded: null,
-            browserCloseError: null
-          },
-          debug: null,
-          completedAt: (/* @__PURE__ */ new Date()).toISOString()
-        });
-        if (willRetry) continue;
-        break;
       }
       await emitAttemptEvent(onAttemptEvent, {
         type: "finished",
         attemptNumber,
-        maxAttempts: MAX_ATTEMPTS,
-        outcome: classifyAttemptError(err),
+        maxAttempts,
+        outcome,
         kernelSessionId: null,
         questionCount: 0,
         durationMs: Date.now() - startedAtMs,
         error: errorMessage(err),
-        willRetry: false,
+        willRetry,
         cleanup: {
           kernelSessionId: null,
           kernelDeleteStarted: false,
@@ -2765,15 +2905,19 @@ async function harvest(rawOptions) {
         debug: null,
         completedAt: (/* @__PURE__ */ new Date()).toISOString()
       });
+      lastError = err;
+      if (willRetry) continue;
+      if (outcome === "captcha") break;
       throw err;
     }
   }
+  if (lastError && !(lastError instanceof CaptchaError)) throw lastError;
   console.warn(JSON.stringify({
     event: "harvest_captcha_exhausted",
-    max_attempts: MAX_ATTEMPTS,
+    max_attempts: maxAttempts,
     session_kind: kernelApiKey ? "kernel" : "local"
   }));
-  throw new CaptchaError(sanitizeVendorName(`CAPTCHA on all ${MAX_ATTEMPTS} fresh sessions. Try again in a few minutes.`));
+  throw new CaptchaError(sanitizeVendorName(`CAPTCHA on all ${maxAttempts} fresh sessions. Try again in a few minutes.`));
 }
 
 export {
@@ -2788,7 +2932,8 @@ export {
   MapsSelectors,
   buildYouTubeChannelVideosUrl,
   BrowserDriver,
+  deleteKernelProxyId,
   resolveKernelProxyId,
   harvest
 };
-//# sourceMappingURL=chunk-TM22BLWP.js.map
+//# sourceMappingURL=chunk-MY3S7EX7.js.map