Browser SDK

The Syntropy Browser SDK captures errors and events from web applications.

npm install @eclosion-tech/syntropy-browser

Basic Setup

import { Syntropy } from '@eclosion-tech/syntropy-browser';

Syntropy.init({
  projectId: 'your-project-id',
  release: '1.0.0',
  environment: 'production',
});

Configuration Options

Syntropy.init({
  // Required
  projectId: 'your-project-id',
  dsn: '/api/ingest',            // Optional ingest endpoint override
  
  // Release tracking
  release: '1.0.0',           // App version
  dist: '42',                 // Build number
  environment: 'production',  // Environment name
  
  // Behavior
  enabled: true,              // Enable/disable SDK
  autoCapture: true,          // Auto-capture unhandled errors
  breadcrumbs: true,          // Collect breadcrumbs
  maxBreadcrumbs: 50,         // Max breadcrumbs to store
  
  // Performance
  flushInterval: 5000,        // Flush interval (ms)
  maxBatchSize: 10,           // Max events per batch
  sampleRate: 1.0,            // Sample rate (0.0 - 1.0)
  
  // Filtering
  beforeSend: (event) => {
    // Return null to drop the event
    if (event.payload.message?.includes('ignore')) {
      return null;
    }
    return event;
  },
  
  // Debugging
  debug: false,               // Log SDK activity
});

Capturing Errors

Automatic Capture

With autoCapture: true (default), Syntropy automatically captures:

• window.onerror - Unhandled JavaScript errors
• unhandledrejection - Unhandled Promise rejections

Manual Capture

try {
  riskyOperation();
} catch (error) {
  Syntropy.captureError(error);
}

// With additional context
Syntropy.captureError(error, { orderId: '12345', component: 'checkout' });

// Capture from error message
Syntropy.captureError('Something went wrong');

Breadcrumbs

Breadcrumbs are automatically collected for:

• Clicks - Element selector, tag name, ID
• Navigation - URL changes (pushState, popstate)
• Console - console.error() calls
• Fetch - Request URL, method, status, duration
• XHR - Request URL, method, status, duration

Custom Breadcrumbs

import { addBreadcrumb } from '@eclosion-tech/syntropy-browser';

addBreadcrumb({
  category: 'user',
  message: 'User clicked checkout button',
  data: { cartItems: 3 },
});

User Identification

// After user logs in
Syntropy.identify({
  id: 'user-123',
  email: 'user@example.com',
  name: 'John Doe',
  plan: 'pro', // Custom properties
});

// Clear on logout
Syntropy.reset();

Custom Events

// Page views
Syntropy.capturePageview('/checkout');

// Custom events
Syntropy.captureEvent('purchase_completed', {
  orderId: '12345',
  amount: 99.99,
  items: 3,
});

// Conversation events
Syntropy.captureConversation('message_sent', {
  conversationId: 'conv_123',
  role: 'user',
});

Tags and Extra Data

// Set global tags (attached to all events)
Syntropy.setTag('version', '2.0.0');
Syntropy.setTag('tenant', 'acme-corp');

// Set global extra data
Syntropy.setExtra('sessionRecordingUrl', 'https://...');

// These are attached to all subsequent events

Flushing Events

Events are batched and sent periodically. Force an immediate flush:

await Syntropy.flush();

Events are automatically flushed on page unload using navigator.sendBeacon.

Script Tag Installation

For simple sites without a build system:

<script
  src="https://unpkg.com/@eclosion-tech/syntropy-browser/dist/browser.min.js"
  data-project-id="your-project-id"
  data-auto-capture="true"
></script>

Framework Integration

React

// src/index.tsx
import { Syntropy } from '@eclosion-tech/syntropy-browser';

Syntropy.init({
  projectId: 'your-project-id',
  release: process.env.REACT_APP_VERSION,
});

// Error boundary
class ErrorBoundary extends React.Component {
  componentDidCatch(error, errorInfo) {
    Syntropy.captureError(error, { componentStack: errorInfo.componentStack });
  }
  // ...
}

Vue

// main.ts
import { Syntropy } from '@eclosion-tech/syntropy-browser';

Syntropy.init({ projectId: 'your-project-id' });

app.config.errorHandler = (error, instance, info) => {
  Syntropy.captureError(error, { info, component: instance?.$options.name });
};

Bundle Size

The browser SDK is designed to be lightweight:

• ~5KB gzipped
• Zero dependencies
• Tree-shakeable

Management APIs

If you need typed access to source maps, chat schemas, and customer APIs from a trusted browser runtime:

import { createSyntropyApiClient } from '@eclosion-tech/syntropy-browser';

const api = createSyntropyApiClient({
  baseUrl: 'https://syntropy.chat/api',
  apiKey: 'syn_sk_xxx',
});

await api.customers.upsert(
  { organizationId: 'org_uuid', projectId: 'project_uuid' },
  { externalId: 'user_123', email: 'user@example.com' }
);

See SDK API Client for the full surface area.