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
- Scrape Endpoint - One-time content extraction
- Screenshots Endpoint - Visual captures
- Crawl Endpoint - Multi-page scraping
Was this page helpful?