Vestara Web SDK

The official Vestara SDK for Web applications.

Installation

npm install @vestara-inc/web

import SDK from "@vestara-inc/web";

SDK.init({
  token: "<VESTARA_SDK_TOKEN>",
  environment: "production",
  targetCategory: "web_frontend",
  serviceName: "Web Storefront",
  appIdentifier: "web-storefront",
});

Defaults:

• apiUrl: https://api.vestara.dev (optional, omit for normal SaaS usage)
• environment: "production"
• sampleRate: 1
• captureConsoleErrors: false
• enableReplay: true startSession() runs automatically inside init().

Runtime target metadata

You can provide metadata to identify this application in the dashboard:

• targetCategory: The kind of target (e.g., web_frontend).
• serviceName: Human-readable name (e.g., Web Storefront).
• appIdentifier: Technical identifier (e.g., web-storefront).

Usage

Identify Users

import SDK from "@vestara-inc/web";

SDK.setUser({
  id: "user_123",
  email: "[email protected]",
});

Logging

SDK.log("info", "Checkout opened", {
  step: "cart",
});
SDK.log("error", "Failed to load cart");

Test Crash Flow

Warning: To trigger a test crash in your application, throw a standard Error. Ensure you remove test crashes before deploying to production.

try {
  throw new Error("Simulated web application error");
} catch (error) {
  SDK.captureError(error as Error, {
    feature: "checkout",
  });
}

Dashboard Verification

1. Perform the test action.
2. Check your Vestara dashboard to confirm logs, crashes, and Failure Trails appear.

Automatic capture

The SDK automatically captures:

• window.onerror
• unhandledrejection
• failed fetch() requests only
• LCP
• FID
• CLS
• FCP
• TTFB
• session replay events:
  • initial full DOM snapshot
  • DOM mutations
  • clicks
  • scrolls
  • input changes
  • URL changes Fetch behavior:
• successful requests are ignored
• SDK ingest requests are ignored
• failures are sent as log events with level: "warn" Replay behavior:
• replay is enabled by default
• only the first 10 minutes of the current SDK session are recorded
• replay chunks are sent as web_replay events every 10 seconds
• a best-effort final chunk is sent on clean stop or page hide
• replay increases bundle size compared with the earlier ultra-tiny target Privacy defaults:
• password inputs are always masked
• elements with data-sensitive are masked recursively
• live form values are never captured
• obvious credit-card and SSN-like text patterns are redacted
• inline scripts are not serialized

Offline queue

• offline events go to localStorage
• maximum queue size is 500
• oldest non-crash events are dropped first
• crash events are preserved when possible
• reconnect flushes offline queue before the in-memory buffer

Before send hook

You can inspect, modify, or drop events before they are queued or sent using the beforeSend option:

SDK.init({
  token: "YOUR_SDK_TOKEN",
  beforeSend: (event) => {
    // Redact sensitive data from payload
    if (event.payload.data?.password) {
      const modified = { ...event, payload: { ...event.payload, data: { ...event.payload.data } } };
      modified.payload.data.password = "[REDACTED]";
      return modified;
    }

    // Drop noisy events
    if (event.payload.message?.includes("heartbeat")) {
      return null; // drops the event
    }

    // Return event unchanged to send normally
    return event;
  },
});

Behavior:

• Return a modified event to send the modified version
• Return null to drop the event
• If the hook throws, the original event is sent (fail-open)

Note: The Vestara backend also applies server-side redaction as a safety layer.

Sampling

sampleRate applies to:

• log
• rum_metric Crash events always send. Replay events always send.

Console error opt-in

Console mirroring is disabled by default.

SDK.init({
  token: "YOUR_SDK_TOKEN",
  captureConsoleErrors: true,
});

Custom API URL

For local development, staging, or self-hosted deployments, pass apiUrl:

SDK.init({
  token: "YOUR_SDK_TOKEN",
  apiUrl: "http://localhost:3000",
  environment: "development",
});

Do not set apiUrl for normal Vestara SaaS usage.

Full example

import SDK from "./SDK";

SDK.init({
  token: "sdk_token_from_backend",
  environment: "staging",
  sampleRate: 0.5,
  enableReplay: true,
});

SDK.setUser({ id: "42", email: "[email protected]" });
SDK.log("info", "Page mounted");
window.addEventListener("click", () => SDK.log("debug", "CTA clicked"));

Backend replay storage

Replay chunks use the normal /v1/ingest flow. On the backend, web_replay events are regrouped by project_id + session_id, gzipped, and stored in Cloudflare R2. Set these env vars on the API:

• R2_ACCOUNT_ID
• R2_ACCESS_KEY_KEY
• R2_SECRET_ACCESS_KEY
• R2_BUCKET

Event schema

Every event sent to /v1/ingest includes:

• event_type
• session_id
• device_id
• timestamp
• sdk_version
• app_version
• os_name
• os_version
• device_model
• environment
• payload

License

This SDK is licensed under the Apache License 2.0.

Copyright 2026 Ahsan Iqbal.

Vestara, the Vestara name, logos, domain, and related branding are not granted under this license.