spectrawl 0.5.0 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "spectrawl",
3
- "version": "0.5.0",
3
+ "version": "0.6.1",
4
4
  "description": "The unified web layer for AI agents. Search (8 engines), stealth browse, auth, act on 24 platforms. Self-hosted.",
5
5
  "main": "src/index.js",
6
6
  "types": "index.d.ts",
package/src/agent.js ADDED
@@ -0,0 +1,295 @@
1
+ /**
2
+ * Spectrawl Agent Engine
3
+ * Natural language browser actions — "click the sign in button", "fill the search box with query".
4
+ * Uses LLM to interpret page DOM and generate Playwright actions.
5
+ */
6
+
7
+ const https = require('https')
8
+
9
+ class AgentEngine {
10
+ constructor(browseEngine, config = {}) {
11
+ this.browseEngine = browseEngine
12
+ this.apiKey = config.apiKey || process.env.GEMINI_API_KEY
13
+ this.openaiKey = config.openaiKey || process.env.OPENAI_API_KEY
14
+ this.model = config.model || 'gemini-2.0-flash'
15
+ }
16
+
17
+ /**
18
+ * Execute a natural language action on a page.
19
+ * @param {string} url - URL to navigate to
20
+ * @param {string} instruction - what to do (e.g. "click the login button")
21
+ * @param {object} opts - options
22
+ * @param {number} opts.maxSteps - max number of actions to take (default 5)
23
+ * @param {boolean} opts.screenshot - take screenshot after action
24
+ * @param {number} opts.timeout - timeout per action in ms
25
+ */
26
+ async act(url, instruction, opts = {}) {
27
+ const maxSteps = opts.maxSteps || 5
28
+ const timeout = opts.timeout || 30000
29
+ const startTime = Date.now()
30
+ const steps = []
31
+
32
+ // Get a browser page
33
+ const { page, context } = await this.browseEngine.getPage({ url, timeout })
34
+
35
+ try {
36
+ // Wait for page to be ready
37
+ await page.waitForLoadState('domcontentloaded', { timeout: 10000 }).catch(() => {})
38
+ await page.waitForTimeout(1000)
39
+
40
+ for (let i = 0; i < maxSteps; i++) {
41
+ // Get simplified DOM
42
+ const dom = await this._getSimplifiedDOM(page)
43
+
44
+ // Ask LLM what to do
45
+ const action = await this._planAction(dom, instruction, steps, page.url())
46
+
47
+ if (action.done) {
48
+ steps.push({ step: i + 1, action: 'done', reason: action.reason })
49
+ break
50
+ }
51
+
52
+ // Execute the action
53
+ try {
54
+ const result = await this._executeAction(page, action)
55
+ steps.push({ step: i + 1, ...action, result: result || 'ok' })
56
+
57
+ // Wait for potential navigation/load
58
+ await page.waitForTimeout(500 + Math.random() * 1000)
59
+ await page.waitForLoadState('domcontentloaded', { timeout: 5000 }).catch(() => {})
60
+ } catch (err) {
61
+ steps.push({ step: i + 1, ...action, error: err.message })
62
+ // Continue trying if there are more steps
63
+ }
64
+ }
65
+
66
+ // Get final page state
67
+ const finalContent = await page.evaluate(() => document.body?.innerText?.slice(0, 10000) || '')
68
+ const finalUrl = page.url()
69
+ const finalTitle = await page.title()
70
+
71
+ let screenshot = null
72
+ if (opts.screenshot) {
73
+ screenshot = await page.screenshot({ type: 'png', fullPage: false })
74
+ }
75
+
76
+ return {
77
+ success: steps.some(s => s.action === 'done' || !s.error),
78
+ url: finalUrl,
79
+ title: finalTitle,
80
+ steps,
81
+ content: finalContent,
82
+ screenshot,
83
+ duration: Date.now() - startTime
84
+ }
85
+ } finally {
86
+ await context.close().catch(() => {})
87
+ }
88
+ }
89
+
90
+ /**
91
+ * Get a simplified DOM representation for the LLM.
92
+ * Strips noise, keeps interactive elements with indices.
93
+ */
94
+ async _getSimplifiedDOM(page) {
95
+ return page.evaluate(() => {
96
+ const elements = []
97
+ const interactiveSelectors = [
98
+ 'a[href]', 'button', 'input', 'textarea', 'select',
99
+ '[role="button"]', '[role="link"]', '[role="tab"]',
100
+ '[onclick]', '[type="submit"]', 'label'
101
+ ]
102
+
103
+ const allElements = document.querySelectorAll(interactiveSelectors.join(','))
104
+
105
+ allElements.forEach((el, idx) => {
106
+ if (!el.offsetParent && el.tagName !== 'INPUT') return // skip hidden
107
+ const rect = el.getBoundingClientRect()
108
+ if (rect.width === 0 && rect.height === 0) return
109
+
110
+ const tag = el.tagName.toLowerCase()
111
+ const type = el.type || ''
112
+ const text = (el.textContent || '').trim().slice(0, 100)
113
+ const placeholder = el.placeholder || ''
114
+ const ariaLabel = el.getAttribute('aria-label') || ''
115
+ const href = el.href || ''
116
+ const value = el.value || ''
117
+ const name = el.name || ''
118
+ const id = el.id || ''
119
+
120
+ // Create a unique selector for this element
121
+ let selector = tag
122
+ if (id) selector = `#${id}`
123
+ else if (name) selector = `${tag}[name="${name}"]`
124
+ else if (ariaLabel) selector = `${tag}[aria-label="${ariaLabel}"]`
125
+
126
+ elements.push({
127
+ idx,
128
+ tag,
129
+ type,
130
+ text: text.slice(0, 80),
131
+ placeholder,
132
+ ariaLabel,
133
+ href: href.slice(0, 100),
134
+ value,
135
+ selector,
136
+ id,
137
+ name
138
+ })
139
+ })
140
+
141
+ return {
142
+ title: document.title,
143
+ url: location.href,
144
+ elements: elements.slice(0, 100) // cap at 100 elements
145
+ }
146
+ })
147
+ }
148
+
149
+ /**
150
+ * Ask LLM to plan the next action.
151
+ */
152
+ async _planAction(dom, instruction, previousSteps, currentUrl) {
153
+ const prompt = `You are a browser automation agent. Given the current page state and instruction, determine the next action.
154
+
155
+ Current URL: ${currentUrl}
156
+ Page title: ${dom.title}
157
+
158
+ Interactive elements on page:
159
+ ${dom.elements.map(e => `[${e.idx}] <${e.tag}${e.type ? ` type="${e.type}"` : ''}${e.id ? ` id="${e.id}"` : ''}${e.name ? ` name="${e.name}"` : ''}> ${e.text || e.placeholder || e.ariaLabel || e.href || '(empty)'}`).join('\n')}
160
+
161
+ Instruction: ${instruction}
162
+
163
+ Previous steps: ${previousSteps.length > 0 ? JSON.stringify(previousSteps) : 'none'}
164
+
165
+ Respond with a JSON object:
166
+ - If the instruction is complete: {"done": true, "reason": "why it's done"}
167
+ - To click: {"action": "click", "elementIdx": 5, "reason": "clicking the login button"}
168
+ - To type: {"action": "type", "elementIdx": 3, "text": "hello", "reason": "filling search box"}
169
+ - To select: {"action": "select", "elementIdx": 7, "value": "option1", "reason": "selecting dropdown"}
170
+ - To press a key: {"action": "press", "key": "Enter", "reason": "submitting form"}
171
+ - To scroll: {"action": "scroll", "direction": "down", "reason": "loading more content"}
172
+
173
+ Only return valid JSON. No explanation.`
174
+
175
+ const result = await this._llmCall(prompt)
176
+ return result
177
+ }
178
+
179
+ /**
180
+ * Execute a planned action on the page.
181
+ */
182
+ async _executeAction(page, action) {
183
+ switch (action.action) {
184
+ case 'click': {
185
+ const elements = await page.$$('a[href], button, input, textarea, select, [role="button"], [role="link"], [role="tab"], [onclick], [type="submit"], label')
186
+ const visibleElements = []
187
+ for (const el of elements) {
188
+ const visible = await el.isVisible().catch(() => false)
189
+ if (visible) visibleElements.push(el)
190
+ }
191
+ const target = visibleElements[action.elementIdx]
192
+ if (!target) throw new Error(`Element [${action.elementIdx}] not found`)
193
+ await target.click({ timeout: 5000 })
194
+ return 'clicked'
195
+ }
196
+
197
+ case 'type': {
198
+ const elements = await page.$$('a[href], button, input, textarea, select, [role="button"], [role="link"], [role="tab"], [onclick], [type="submit"], label')
199
+ const visibleElements = []
200
+ for (const el of elements) {
201
+ const visible = await el.isVisible().catch(() => false)
202
+ if (visible) visibleElements.push(el)
203
+ }
204
+ const target = visibleElements[action.elementIdx]
205
+ if (!target) throw new Error(`Element [${action.elementIdx}] not found`)
206
+ await target.fill('')
207
+ await target.type(action.text, { delay: 50 + Math.random() * 100 })
208
+ return 'typed'
209
+ }
210
+
211
+ case 'select': {
212
+ const elements = await page.$$('a[href], button, input, textarea, select, [role="button"], [role="link"], [role="tab"], [onclick], [type="submit"], label')
213
+ const visibleElements = []
214
+ for (const el of elements) {
215
+ const visible = await el.isVisible().catch(() => false)
216
+ if (visible) visibleElements.push(el)
217
+ }
218
+ const target = visibleElements[action.elementIdx]
219
+ if (!target) throw new Error(`Element [${action.elementIdx}] not found`)
220
+ await target.selectOption(action.value)
221
+ return 'selected'
222
+ }
223
+
224
+ case 'press':
225
+ await page.keyboard.press(action.key)
226
+ return 'pressed'
227
+
228
+ case 'scroll':
229
+ await page.evaluate((dir) => {
230
+ window.scrollBy(0, dir === 'up' ? -500 : 500)
231
+ }, action.direction)
232
+ return 'scrolled'
233
+
234
+ default:
235
+ throw new Error(`Unknown action: ${action.action}`)
236
+ }
237
+ }
238
+
239
+ async _llmCall(prompt) {
240
+ if (this.apiKey) {
241
+ const url = `https://generativelanguage.googleapis.com/v1beta/models/${this.model}:generateContent?key=${this.apiKey}`
242
+ const body = {
243
+ contents: [{ parts: [{ text: prompt }] }],
244
+ generationConfig: { responseMimeType: 'application/json', temperature: 0.1 }
245
+ }
246
+
247
+ const response = await this._post(url, body)
248
+ const text = response?.candidates?.[0]?.content?.parts?.[0]?.text
249
+ if (!text) throw new Error('Empty LLM response')
250
+ return JSON.parse(text)
251
+ } else if (this.openaiKey) {
252
+ const url = 'https://api.openai.com/v1/chat/completions'
253
+ const body = {
254
+ model: 'gpt-4o-mini',
255
+ messages: [{ role: 'user', content: prompt }],
256
+ response_format: { type: 'json_object' },
257
+ temperature: 0.1
258
+ }
259
+ const response = await this._post(url, body, { 'Authorization': `Bearer ${this.openaiKey}` })
260
+ return JSON.parse(response?.choices?.[0]?.message?.content)
261
+ }
262
+ throw new Error('No LLM API key configured')
263
+ }
264
+
265
+ _post(url, body, extraHeaders = {}) {
266
+ return new Promise((resolve, reject) => {
267
+ const urlObj = new URL(url)
268
+ const data = JSON.stringify(body)
269
+ const opts = {
270
+ hostname: urlObj.hostname,
271
+ path: urlObj.pathname + urlObj.search,
272
+ method: 'POST',
273
+ headers: {
274
+ 'Content-Type': 'application/json',
275
+ 'Content-Length': Buffer.byteLength(data),
276
+ ...extraHeaders
277
+ }
278
+ }
279
+ const req = https.request(opts, res => {
280
+ let responseData = ''
281
+ res.on('data', chunk => responseData += chunk)
282
+ res.on('end', () => {
283
+ try { resolve(JSON.parse(responseData)) }
284
+ catch (e) { reject(new Error(`Invalid JSON: ${responseData.slice(0, 200)}`)) }
285
+ })
286
+ })
287
+ req.on('error', reject)
288
+ req.setTimeout(30000, () => { req.destroy(); reject(new Error('LLM timeout')) })
289
+ req.write(data)
290
+ req.end()
291
+ })
292
+ }
293
+ }
294
+
295
+ module.exports = { AgentEngine }
@@ -45,8 +45,42 @@ class BrowseEngine {
45
45
  return this._browseRemoteCamoufox(url, opts)
46
46
  }
47
47
 
48
+ // Site-specific pre-routing: use known-working alternatives before trying direct browse
49
+ const siteOverride = this._getSiteOverride(url)
50
+ if (siteOverride && !opts._skipOverride) {
51
+ try {
52
+ const result = await siteOverride(url, opts)
53
+ if (result && !result.blocked && (result.content || '').length > 50) {
54
+ return result // Override succeeded with content
55
+ }
56
+ if (result && result.blocked) {
57
+ return result // Override confirmed site is blocked — return with actionable message
58
+ }
59
+ // Override returned empty/null — fall through to normal browse
60
+ } catch (e) {
61
+ // Override failed — fall through
62
+ }
63
+ }
64
+
48
65
  try {
49
- return await this._browsePlaywright(url, opts)
66
+ const result = await this._browsePlaywright(url, opts)
67
+
68
+ // Post-browse content quality check
69
+ if (result && result.blocked) {
70
+ console.log(`[browse] Blocked on ${url}: ${result.blockType} — ${result.blockDetail}`)
71
+ // Try site override as fallback
72
+ if (siteOverride) {
73
+ try {
74
+ const fallback = await siteOverride(url, { ...opts, _skipOverride: true })
75
+ if (fallback && !fallback.blocked && (fallback.content || '').length > 50) {
76
+ fallback._fallback = true
77
+ return fallback
78
+ }
79
+ } catch (e) { /* fallback failed too */ }
80
+ }
81
+ }
82
+
83
+ return result
50
84
  } catch (err) {
51
85
  // If blocked and remote Camoufox available, try that
52
86
  if (this._isBlocked(err) && this.remoteCamoufox) {
@@ -64,6 +98,101 @@ class BrowseEngine {
64
98
  }
65
99
  }
66
100
 
101
+ /**
102
+ * Get site-specific override for sites that block datacenter IPs.
103
+ * Returns a function that fetches content via alternative methods.
104
+ */
105
+ _getSiteOverride(url) {
106
+ // Reddit: datacenter IPs are fully blocked (browse, JSON, RSS all fail)
107
+ // Fallback: return block info with actionable message + try Jina
108
+ if (url.includes('reddit.com')) {
109
+ return async (originalUrl, opts) => {
110
+ // Try Jina Reader first (sometimes works)
111
+ try {
112
+ const jinaUrl = `https://r.jina.ai/${originalUrl}`
113
+ const h = require('https')
114
+ const content = await new Promise((resolve, reject) => {
115
+ const req = h.get(jinaUrl, {
116
+ headers: { 'Accept': 'text/plain', 'User-Agent': 'Spectrawl/1.0' },
117
+ timeout: 10000
118
+ }, res => {
119
+ if (res.statusCode !== 200) return resolve(null)
120
+ let data = ''
121
+ res.on('data', c => data += c)
122
+ res.on('end', () => resolve(data))
123
+ })
124
+ req.on('error', () => resolve(null))
125
+ req.setTimeout(10000, () => { req.destroy(); resolve(null) })
126
+ })
127
+
128
+ if (content && content.length > 200 && !content.includes('blocked by network')) {
129
+ return {
130
+ content,
131
+ url: originalUrl,
132
+ title: 'Reddit (via Jina Reader)',
133
+ statusCode: 200,
134
+ cached: false,
135
+ engine: 'jina-reader',
136
+ blocked: false
137
+ }
138
+ }
139
+ } catch (e) { /* try next */ }
140
+
141
+ // All direct methods fail from datacenter IPs
142
+ // Return explicit block with guidance
143
+ return {
144
+ content: '',
145
+ url: originalUrl,
146
+ title: 'Reddit',
147
+ statusCode: 403,
148
+ cached: false,
149
+ engine: 'blocked',
150
+ blocked: true,
151
+ blockType: 'reddit',
152
+ blockDetail: 'Reddit blocks all datacenter IPs. Use /search with a Reddit-related query to get cached Reddit content via Google, or configure a residential proxy.'
153
+ }
154
+ }
155
+ }
156
+
157
+ // Amazon: try Jina Reader
158
+ if (url.includes('amazon.com') || url.includes('amazon.co')) {
159
+ return async (originalUrl, opts) => {
160
+ try {
161
+ const jinaUrl = `https://r.jina.ai/${originalUrl}`
162
+ const h = require('https')
163
+ const content = await new Promise((resolve, reject) => {
164
+ const req = h.get(jinaUrl, {
165
+ headers: { 'Accept': 'text/plain', 'User-Agent': 'Spectrawl/1.0' },
166
+ timeout: 10000
167
+ }, res => {
168
+ if (res.statusCode !== 200) return resolve(null)
169
+ let data = ''
170
+ res.on('data', c => data += c)
171
+ res.on('end', () => resolve(data))
172
+ })
173
+ req.on('error', () => resolve(null))
174
+ req.setTimeout(10000, () => { req.destroy(); resolve(null) })
175
+ })
176
+
177
+ if (content && content.length > 100) {
178
+ return {
179
+ content,
180
+ url: originalUrl,
181
+ title: 'Amazon (via Jina Reader)',
182
+ statusCode: 200,
183
+ cached: false,
184
+ engine: 'jina-reader',
185
+ blocked: false
186
+ }
187
+ }
188
+ } catch (e) { /* fall through */ }
189
+ return null
190
+ }
191
+ }
192
+
193
+ return null
194
+ }
195
+
67
196
  /**
68
197
  * Launch Playwright with the best available browser.
69
198
  * Priority: Camoufox binary > stealth Chromium > vanilla Chromium
@@ -120,6 +249,40 @@ class BrowseEngine {
120
249
  const context = await this._createContext(browser, opts)
121
250
  const page = await context.newPage()
122
251
 
252
+ // Network request capturing
253
+ const networkRequests = []
254
+ if (opts.captureNetwork) {
255
+ page.on('request', req => {
256
+ const resourceType = req.resourceType()
257
+ if (['xhr', 'fetch'].includes(resourceType)) {
258
+ networkRequests.push({
259
+ url: req.url(),
260
+ method: req.method(),
261
+ resourceType,
262
+ headers: opts.captureNetworkHeaders ? req.headers() : undefined,
263
+ postData: req.postData() || undefined
264
+ })
265
+ }
266
+ })
267
+ page.on('response', async res => {
268
+ const req = res.request()
269
+ const resourceType = req.resourceType()
270
+ if (['xhr', 'fetch'].includes(resourceType)) {
271
+ const existing = networkRequests.find(r => r.url === req.url() && r.method === req.method())
272
+ if (existing) {
273
+ existing.status = res.status()
274
+ existing.contentType = res.headers()['content-type'] || null
275
+ if (opts.captureNetworkBody) {
276
+ try {
277
+ const body = await res.text().catch(() => null)
278
+ if (body && body.length < 50000) existing.body = body
279
+ } catch (e) { /* ignore */ }
280
+ }
281
+ }
282
+ }
283
+ })
284
+ }
285
+
123
286
  try {
124
287
  if (opts._cookies) {
125
288
  await context.addCookies(opts._cookies)
@@ -168,6 +331,11 @@ class BrowseEngine {
168
331
  result.cached = false
169
332
  result.engine = this._engine
170
333
 
334
+ // Attach captured network requests
335
+ if (opts.captureNetwork && networkRequests.length > 0) {
336
+ result.networkRequests = networkRequests
337
+ }
338
+
171
339
  // Detect block pages (Cloudflare, Akamai, etc.)
172
340
  const blockInfo = detectBlockPage(result.content, result.title, result.html, result.url)
173
341
  if (blockInfo) {
@@ -363,6 +531,37 @@ function detectBlockPage(content, title, html, url) {
363
531
  return { type: 'recaptcha', detail: 'reCAPTCHA challenge page' }
364
532
  }
365
533
 
534
+ // Reddit network block
535
+ if (text.includes('been blocked by network security') ||
536
+ text.includes('log in to your reddit account') && text.includes('blocked') ||
537
+ text.includes('whoa there, pardner') ||
538
+ text.includes('your request has been blocked') && url?.includes('reddit')) {
539
+ return { type: 'reddit', detail: 'Reddit network-level IP block (datacenter IP detected)' }
540
+ }
541
+
542
+ // Amazon bot detection / CAPTCHA wall
543
+ if ((text.includes('continue shopping') && text.length < 300) ||
544
+ text.includes('sorry, we just need to make sure you') ||
545
+ text.includes('enter the characters you see below') ||
546
+ (text.includes('robot') && text.includes('sorry') && url?.includes('amazon')) ||
547
+ (titleLower.includes('robot check') && url?.includes('amazon'))) {
548
+ return { type: 'amazon', detail: 'Amazon CAPTCHA/bot detection wall' }
549
+ }
550
+
551
+ // LinkedIn auth wall / cookie consent wall
552
+ if ((text.includes('sign in') && text.includes('linkedin') && text.length < 1000) ||
553
+ (text.includes('join now') && text.includes('linkedin') && text.length < 1000) ||
554
+ (text.includes('essential and non-essential cookies') && url?.includes('linkedin'))) {
555
+ return { type: 'linkedin', detail: 'LinkedIn authentication or cookie consent wall' }
556
+ }
557
+
558
+ // Google / YouTube consent
559
+ if (text.includes('before you continue to google') ||
560
+ text.includes('before you continue to youtube') ||
561
+ (titleLower.includes('consent') && (url?.includes('google') || url?.includes('youtube')))) {
562
+ return { type: 'google-consent', detail: 'Google/YouTube consent page' }
563
+ }
564
+
366
565
  // Generic bot detection signals
367
566
  if (text.length < 200 && (
368
567
  text.includes('access denied') || text.includes('403 forbidden') ||
@@ -371,6 +570,16 @@ function detectBlockPage(content, title, html, url) {
371
570
  return { type: 'generic', detail: 'Generic bot detection or access denied page' }
372
571
  }
373
572
 
573
+ // Content quality heuristic — suspiciously short content from sites that should have more
574
+ if (text.length < 100 && text.length > 0 && url) {
575
+ const knownLargeSites = ['reddit.com', 'amazon.com', 'linkedin.com', 'facebook.com',
576
+ 'twitter.com', 'x.com', 'instagram.com', 'g2.com', 'yelp.com',
577
+ 'glassdoor.com', 'indeed.com', 'zillow.com', 'ebay.com']
578
+ if (knownLargeSites.some(s => url.includes(s))) {
579
+ return { type: 'suspected-block', detail: `Suspiciously short content (${text.length} chars) from ${url} — likely blocked or gated` }
580
+ }
581
+ }
582
+
374
583
  return null
375
584
  }
376
585
 
package/src/crawl.js CHANGED
@@ -90,6 +90,29 @@ class CrawlEngine {
90
90
  const failed = []
91
91
  let activeCount = 0
92
92
 
93
+ // Sitemap-based crawling: pre-seed queue with sitemap URLs
94
+ if (config.useSitemap !== false) {
95
+ try {
96
+ const sitemapUrls = await fetchSitemap(startUrl)
97
+ if (sitemapUrls.length > 0) {
98
+ for (const sUrl of sitemapUrls.slice(0, config.maxPages)) {
99
+ const norm = normalizeUrl(sUrl)
100
+ if (!visited.has(norm) && this._inScope(sUrl, baseDomain, basePrefix, config.scope)) {
101
+ if (!config.skipPatterns.some(p => p.test(sUrl))) {
102
+ if (this._matchesFilters(sUrl, config.includePatterns, config.excludePatterns)) {
103
+ visited.add(norm)
104
+ queue.push({ url: sUrl, depth: 0 })
105
+ }
106
+ }
107
+ }
108
+ }
109
+ console.log(`[crawl] Pre-seeded ${Math.min(sitemapUrls.length, config.maxPages)} URLs from sitemap`)
110
+ }
111
+ } catch (e) {
112
+ console.log(`[crawl] Sitemap fetch failed, continuing with link discovery`)
113
+ }
114
+ }
115
+
93
116
  // Process queue with concurrency control
94
117
  const processUrl = async (item) => {
95
118
  const { url, depth } = item
@@ -177,6 +200,14 @@ class CrawlEngine {
177
200
  }).join('\n\n---\n\n')
178
201
  }
179
202
 
203
+ // Webhook notification
204
+ if (config.webhook) {
205
+ sendWebhook(config.webhook, {
206
+ event: 'crawl_complete',
207
+ ...result
208
+ }).catch(err => console.error('[crawl] Webhook failed:', err.message))
209
+ }
210
+
180
211
  return result
181
212
  }
182
213
 
@@ -371,6 +402,93 @@ function resolveUrl(url, base) {
371
402
  }
372
403
  }
373
404
 
405
+ /**
406
+ * Fetch and parse sitemap.xml for a domain.
407
+ * Returns array of URLs found in the sitemap.
408
+ */
409
+ async function fetchSitemap(startUrl) {
410
+ const { URL } = require('url')
411
+ const base = new URL(startUrl)
412
+ const sitemapUrls = [
413
+ `${base.origin}/sitemap.xml`,
414
+ `${base.origin}/sitemap_index.xml`,
415
+ `${base.origin}/sitemap/sitemap.xml`
416
+ ]
417
+
418
+ for (const sitemapUrl of sitemapUrls) {
419
+ try {
420
+ const xml = await fetchText(sitemapUrl, 5000)
421
+ if (!xml || !xml.includes('<url') && !xml.includes('<sitemap')) continue
422
+
423
+ const urls = []
424
+ // Extract <loc> URLs from sitemap
425
+ const locMatches = xml.matchAll(/<loc>\s*(.*?)\s*<\/loc>/gi)
426
+ for (const match of locMatches) {
427
+ const loc = match[1].trim()
428
+ // If it's a sitemap index, recursively fetch
429
+ if (loc.endsWith('.xml') || loc.includes('sitemap')) {
430
+ try {
431
+ const subXml = await fetchText(loc, 5000)
432
+ if (subXml) {
433
+ const subMatches = subXml.matchAll(/<loc>\s*(.*?)\s*<\/loc>/gi)
434
+ for (const subMatch of subMatches) {
435
+ const subLoc = subMatch[1].trim()
436
+ if (!subLoc.endsWith('.xml')) urls.push(subLoc)
437
+ }
438
+ }
439
+ } catch (e) { /* skip failed sub-sitemaps */ }
440
+ } else {
441
+ urls.push(loc)
442
+ }
443
+ }
444
+ if (urls.length > 0) {
445
+ console.log(`[crawl] Found sitemap at ${sitemapUrl} with ${urls.length} URLs`)
446
+ return urls
447
+ }
448
+ } catch (e) { /* try next */ }
449
+ }
450
+ return []
451
+ }
452
+
453
+ function fetchText(url, timeout = 5000) {
454
+ const h = url.startsWith('https') ? require('https') : require('http')
455
+ return new Promise((resolve, reject) => {
456
+ const req = h.get(url, { timeout, headers: { 'User-Agent': 'Spectrawl/1.0 (sitemap crawler)' } }, res => {
457
+ if (res.statusCode !== 200) return resolve(null)
458
+ let data = ''
459
+ res.on('data', chunk => data += chunk)
460
+ res.on('end', () => resolve(data))
461
+ })
462
+ req.on('error', () => resolve(null))
463
+ req.setTimeout(timeout, () => { req.destroy(); resolve(null) })
464
+ })
465
+ }
466
+
467
+ /**
468
+ * Send a webhook notification.
469
+ */
470
+ async function sendWebhook(webhookUrl, data) {
471
+ const h = webhookUrl.startsWith('https') ? require('https') : require('http')
472
+ const body = JSON.stringify(data)
473
+ const urlObj = new URL(webhookUrl)
474
+ return new Promise((resolve) => {
475
+ const req = h.request({
476
+ hostname: urlObj.hostname,
477
+ port: urlObj.port,
478
+ path: urlObj.pathname + urlObj.search,
479
+ method: 'POST',
480
+ headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) }
481
+ }, res => {
482
+ res.on('data', () => {})
483
+ res.on('end', () => resolve(true))
484
+ })
485
+ req.on('error', () => resolve(false))
486
+ req.setTimeout(10000, () => { req.destroy(); resolve(false) })
487
+ req.write(body)
488
+ req.end()
489
+ })
490
+ }
491
+
374
492
  function normalizeUrl(url) {
375
493
  try {
376
494
  const u = new URL(url)