velyn-sdk

Lightweight browser SDK that captures frontend events (clicks, API calls, errors) and sends them to a Velyn backend for causal timeline analysis and automated Playwright test generation.

Install

npm install velyn-sdk

Quick Start — Auto Mode

Drop this into your app's entry point. The SDK will automatically patch fetch, XMLHttpRequest, clicks, window.onerror, and unhandled promise rejections.

import { initVelyn } from "velyn-sdk";

const velyn = initVelyn({
  endpoint: "https://your-velyn-backend.com/ingest",
  apiKey: "your-api-key",
});

// That's it. Events are captured and flushed automatically.

// To stop capturing (e.g. on logout):
// velyn.stop();

Manual Tracking

If you prefer full control, disable auto-instrumentation and track events yourself:

import { Velyn } from "velyn-sdk";

const velyn = new Velyn({
  endpoint: "https://your-velyn-backend.com/ingest",
  apiKey: "your-api-key",
  autoInstrument: false,
});
velyn.start();

// Track a user action
velyn.trackAction("click", "#checkout-button");

// Track an API call
velyn.trackApi("/api/checkout", "POST", 500);

// Track an error
velyn.trackError("TypeError: Cannot read properties of undefined", "TypeError");

Sentry Integration

If your app already uses Sentry, Velyn can piggyback on Sentry events to automatically extract breadcrumbs and errors — no duplicate instrumentation needed:

import * as Sentry from "@sentry/browser";
import { initVelyn } from "velyn-sdk";

const velyn = initVelyn({
  endpoint: "https://your-velyn-backend.com/ingest",
  apiKey: "your-api-key",
  autoInstrument: false, // Sentry already captures everything
});

Sentry.init({
  dsn: "your-sentry-dsn",
  beforeSend(event) {
    velyn.captureFromSentryEvent(event);
    return event;
  },
});

Configuration

| Option | Type | Default | Description | |---|---|---|---| | endpoint | string | required | Full URL of the Velyn ingestion endpoint | | apiKey | string | undefined | Sent as x-api-key header | | autoInstrument | boolean | true | Patch browser APIs to capture events automatically | | flushIntervalMs | number | 5000 | Milliseconds between automatic flushes | | maxBatchSize | number | 30 | Max events sent per flush | | sessionId | string | auto-generated | Override the generated session ID | | onFlush | (result) => void | undefined | Callback after each successful flush |

API

initVelyn(config): Velyn

Creates and starts a Velyn instance with autoInstrument: true by default.

new Velyn(config)

Creates an instance without starting it. Call .start() when ready.

Instance Methods

| Method | Description | |---|---| | .start() | Begin flushing and (if enabled) auto-instrumentation | | .stop() | Stop flushing and remove all patches | | .flush() | Immediately send queued events | | .trackAction(actionType, target, value?) | Manually track a user action | | .trackApi(url, method, status) | Manually track an API request | | .trackError(message, name?, stack?) | Manually track an error | | .captureFromSentryEvent(event) | Extract and enqueue events from a Sentry event object |

License

MIT