Supacrawler Docs
SDKsTypeScript SDK

Watch Endpoint

Monitor websites for changes using the TypeScript SDK

Basic Usage

import { SupacrawlerClient } from '@supacrawler/js'

const client = new SupacrawlerClient({ apiKey: 'YOUR_API_KEY' })

// Create watch
const created = await client.watchCreate({
  url: 'https://example.com/pricing',
  frequency: 'daily',
  notify_email: '[email protected]',
  notification_preference: 'changes_only'
})

console.log('watch created:', created.watch_id)

Frequencies

// Hourly checks
const hourly = await client.watchCreate({
  url: 'https://example.com',
  frequency: 'hourly',
  notify_email: '[email protected]'
})

// Daily checks
const daily = await client.watchCreate({
  url: 'https://example.com',
  frequency: 'daily',
  notify_email: '[email protected]'
})

// Weekly checks
const weekly = await client.watchCreate({
  url: 'https://example.com',
  frequency: 'weekly',
  notify_email: '[email protected]'
})

Notification Preferences

Changes Only

const watch = await client.watchCreate({
  url: 'https://example.com/blog',
  frequency: 'hourly',
  notify_email: '[email protected]',
  notification_preference: 'changes_only'  // Only on changes
})

All Runs

const watch = await client.watchCreate({
  url: 'https://example.com',
  frequency: 'daily',
  notify_email: '[email protected]',
  notification_preference: 'all_runs'  // Every check
})

Include Content

With HTML

const watch = await client.watchCreate({
  url: 'https://example.com',
  frequency: 'hourly',
  notify_email: '[email protected]',
  include_html: true  // Include HTML content
})

With Screenshot

const watch = await client.watchCreate({
  url: 'https://example.com',
  frequency: 'daily',
  notify_email: '[email protected]',
  include_image: true,  // Include screenshot
  full_page: true,      // Full page screenshot
  quality: 85          // JPEG quality
})

Specific Elements

Monitor with CSS Selector

const watch = await client.watchCreate({
  url: 'https://example.com/pricing',
  frequency: 'hourly',
  notify_email: '[email protected]',
  selector: '#pricing-table',  // Only watch this element
  notification_preference: 'changes_only'
})

Managing Watches

Get Watch Details

// Get details
const details = await client.watchGet(watch.watch_id)

console.log('status:', details.watch?.status)
console.log('last check:', details.watch?.last_check)
console.log('results:', details.results?.length)

// Access latest result
if (details.results && details.results.length > 0) {
  const latest = details.results[0]
  console.log('has changed:', latest.has_changed)
  console.log('change type:', latest.change_type)
}

List All Watches

// List all watches
const list = await client.watchList()

console.log(`total watches: ${list.total}`)

list.watches?.forEach(watch => {
  console.log(`ID: ${watch.id}`)
  console.log(`URL: ${watch.url}`)
  console.log(`frequency: ${watch.frequency}`)
  console.log(`status: ${watch.status}`)
  console.log('-'.repeat(50))
})

Pause and Resume

// Pause watch
await client.watchPause(watch.watch_id)
console.log('watch paused')

// Resume watch
await client.watchResume(watch.watch_id)
console.log('watch resumed')

Manual Check

// Trigger immediate check
await client.watchCheck(watch.watch_id)
console.log('manual check triggered')

Delete Watch

// Delete watch
await client.watchDelete(watch.watch_id)
console.log('watch deleted')

Complete Example

import { SupacrawlerClient } from '@supacrawler/js'

async function main() {
  const client = new SupacrawlerClient({
    apiKey: process.env.SUPACRAWLER_API_KEY || 'YOUR_API_KEY'
  })

  try {
    // Create comprehensive watch
    const created = await client.watchCreate({
      url: 'https://example.com/pricing',
      frequency: 'hourly',
      notify_email: '[email protected]',
      notification_preference: 'changes_only',
      selector: '#pricing-table',
      include_html: true,
      include_image: true,
      full_page: true,
      quality: 85
    })

    console.log(`✅ watch created: ${created.watch_id}`)

    // Get details
    const details = await client.watchGet(created.watch_id)
    console.log('\nwatch details:')
    console.log(`URL: ${details.watch?.url}`)
    console.log(`status: ${details.watch?.status}`)
    console.log(`frequency: ${details.watch?.frequency}`)

    // Check results
    if (details.results && details.results.length > 0) {
      console.log('\nlatest result:')
      const latest = details.results[0]
      console.log(`executed at: ${latest.executed_at}`)
      console.log(`has changed: ${latest.has_changed}`)

      if (latest.image_url) {
        console.log(`screenshot: ${latest.image_url}`)
      }
    }

    // List all watches
    const list = await client.watchList()
    console.log(`\ntotal active watches: ${list.total}`)

    // Trigger manual check
    console.log('\ntriggering manual check...')
    await client.watchCheck(created.watch_id)

    // Pause watch
    console.log('pausing watch...')
    await client.watchPause(created.watch_id)

    // Resume watch
    console.log('resuming watch...')
    await client.watchResume(created.watch_id)

    // Clean up (optional)
    // await client.watchDelete(created.watch_id)

  } catch (error) {
    console.error('watch operation failed:', error)
    process.exit(1)
  }
}

main()

Response Structure

interface WatchCreateResponse {
  success: boolean
  watch_id: string
  message: string
}

interface WatchGetResponse {
  success: boolean
  watch?: {
    id: string
    user_id: string
    url: string
    frequency: string
    notify_email: string
    notification_preference?: string
    include_html: boolean
    include_image: boolean
    full_page: boolean
    quality: number
    selector?: string
    status: string
    last_check?: string
    created_at: string
    updated_at: string
  }
  results?: Array<{
    id?: string
    executed_at: string
    has_changed: boolean
    change_type?: string
    content_hash?: string
    content?: string
    html_content?: string
    image_url?: string
  }>
}

interface WatchListResponse {
  success: boolean
  total: number
  watches?: Array<Watch>
}

Use Cases

Price Monitoring

// Monitor pricing page
const watch = await client.watchCreate({
  url: 'https://competitor.com/pricing',
  frequency: 'daily',
  notify_email: '[email protected]',
  selector: '#pricing-table',
  notification_preference: 'changes_only',
  include_html: true
})

Product Availability

// Watch for product in stock
const watch = await client.watchCreate({
  url: 'https://store.com/product/limited-edition',
  frequency: 'hourly',
  notify_email: '[email protected]',
  selector: '.product-availability',
  notification_preference: 'changes_only'
})

Blog Updates

// Monitor blog for new posts
const watch = await client.watchCreate({
  url: 'https://competitor.com/blog',
  frequency: 'daily',
  notify_email: '[email protected]',
  notification_preference: 'changes_only',
  include_image: true,
  full_page: true
})

Error Handling

try {
  const created = await client.watchCreate({
    url: 'https://example.com',
    frequency: 'hourly',
    notify_email: '[email protected]'
  })

  console.log(`✅ watch created: ${created.watch_id}`)

  const details = await client.watchGet(created.watch_id)
  console.log(`watch status: ${details.watch?.status}`)

} catch (error) {
  console.error('watch operation failed:', error)
}

Next Steps

Was this page helpful?