@vybesec/sdk

Browser SDK for sending VybeSec events to your ingest endpoint. This package is browser-only (not intended for Node.js or React Native yet).

Server SDK inventory

• Node.js: @vybesec/node
• Supabase Deno: @vybesec/deno
• Cloudflare Workers: @vybesec/cloudflare
• Python: vybesec (PyPI)
• Go: github.com/vybesec/vybesec-go
• Ruby: vybesec (RubyGems)
• PHP: vybesec/sdk (Composer)
• Rust: vybesec (crates.io)

Install (npm)

npm install @vybesec/sdk

import { init, captureError, captureEvent } from "@vybesec/sdk";

init({
  key: "pk_xxxxxxxxxxxxxxxx",
  environment: "production",
  platform: "other"
});

captureError(new Error("Something broke"));

captureEvent({
  type: "custom",
  message: "Checkout completed",
  timestamp: Date.now(),
  extra: { orderId: "order_123" }
});

CDN (script tag)

<script src="https://cdn.vybesec.com/v1/sdk.js?v=20260326"></script>
<script>
  VybeSec.init({
    key: "pk_xxxxxxxxxxxxxxxx",
    environment: "production"
  });

  VybeSec.captureError(new Error("Something broke"));
</script>

Dev test snippet

Paste this into a dev page to confirm events are flowing:

<button id="vs-test-success">Trigger test success</button>
<button id="vs-test-error">Trigger test error</button>
<script>
  const sdk = window.VybeSec?.vybesec ?? window.VybeSec;
  document.getElementById("vs-test-success")?.addEventListener("click", () => {
    sdk?.captureEvent?.({
      type: "info",
      message: "VybeSec test success",
      timestamp: Date.now()
    });
  });
  document.getElementById("vs-test-error")?.addEventListener("click", () => {
    sdk?.captureError?.(new Error("VybeSec test error"));
  });
</script>

Configuration

| Option | Type | Description | Default | | --- | --- | --- | --- | | key | string | Project public key (DSN key). | Required | | environment | "production" | "staging" | "development" | Environment tag. | "production" | | platform | Platform | Tool/framework tag (examples: lovable, cursor, nextjs, react, vue, svelte, react-native, expo, other). | "other" | | release | string | Release identifier. | "" | | userId | string | User identifier. | undefined | | sampleRate | number | 0–1 sampling. | 1 | | maxBuffer | number | Max buffered events. | 100 | | maxEventsPerMinute | number | Client-side rate limit. | 120 |

Full platform list is documented in the VybeSec docs and kept in sync with the dashboard.

Events

captureError(error, context?)

Sends a normalized error event. Automatically attaches URL, session, environment, and release tags.

captureEvent(event)

Send a custom event. The SDK normalizes and scrubs sensitive values.

Supported event shape:

type RawEvent = {
  type: "error" | "warning" | "info" | "performance" | "custom";
  message: string;
  stackTrace?: string;
  errorType?: string;
  url?: string;
  requestUrl?: string;
  requestMethod?: string;
  responseStatus?: number;
  sessionId?: string;
  userId?: string;
  timestamp: number;
  tags?: Record<string, string>;
  extra?: Record<string, unknown>;
};

Automatic instrumentation

The SDK captures:

• window.error and unhandledrejection
• Failed fetch and XHR responses
• SPA navigation changes
• Flushes queued events on tab close / hidden

Backward compatibility policy

We treat patch and minor releases as backward compatible for the public API:

• init, captureError, captureEvent, and the global VybeSec object

Breaking changes will only ship with a major version bump and will be documented in the changelog.

Security & PII

The SDK scrubs obvious secrets (API keys, passwords, bearer tokens) before sending events. If you need deeper redaction, use a custom captureEvent wrapper to scrub payloads before calling the SDK.