@snapfail/sdk

Core SDK for Snapfail — error monitoring for modern web apps.

Snapfail renders your pages in a real browser, diffs screenshots pixel-by-pixel, and asserts that critical DOM nodes are alive. This package is the foundation: it captures browser errors, resolves source maps server-side, and ships events to your beacon endpoint.

Installation

npm install @snapfail/sdk
# or
pnpm add @snapfail/sdk

Entry points

The package ships three separate entry points to keep browser and server bundles clean:

| Import | Environment | Use | |--------|-------------|-----| | @snapfail/sdk | Universal | Snapfail class, types, ConsoleTransport | | @snapfail/sdk/browser | Browser only | BrowserCollector — intercepts errors and sends beacons | | @snapfail/sdk/server | Server / edge | beaconHandler — receives beacons and resolves source maps |

Usage

Initialize (server / edge)

import { Snapfail, ConsoleTransport } from '@snapfail/sdk'

Snapfail.init({
  dsn: '/api/beacon',
  environment: 'production',
  transport: new ConsoleTransport(), // swap for your own transport
})

Collect browser errors

import { BrowserCollector } from '@snapfail/sdk/browser'

BrowserCollector.init({
  dsn: '/api/beacon',
  environment: 'production',
})

Automatically intercepts window.onerror and unhandledrejection, deduplicates events, and sends them via navigator.sendBeacon (with a fetch keepalive fallback).

Handle incoming beacons (server / edge)

import { beaconHandler } from '@snapfail/sdk/server'

// In your request handler:
if (request.method === 'POST' && url.pathname === '/api/beacon') {
  return beaconHandler(request, url, {
    mode: 'dev', // or 'prod'
    origin: url.origin,
  })
}

Resolves V8 stack frames against inline source maps and forwards the enriched event to the Snapfail singleton.

Custom transport

Implement ITransport to send events wherever you want:

import type { ITransport, BeaconEvent, SnapfailEnvironment } from '@snapfail/sdk'

class MyTransport implements ITransport {
  connect(config: { dsn: string; environment: SnapfailEnvironment }) {}
  send(event: BeaconEvent) {
    fetch('https://ingest.example.com/events', {
      method: 'POST',
      body: JSON.stringify(event),
    })
  }
}

Snapfail.init({ dsn: '/api/beacon', transport: new MyTransport() })

License

MIT