> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kodostatus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Beacon SDK

> Track JavaScript errors and performance from your frontend

The Beacon SDK captures JavaScript errors, performance metrics, and custom logs from your frontend applications.

## Installation

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install @kodo-status/beacon
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add @kodo-status/beacon
    ```
  </Tab>

  <Tab title="CDN">
    ```html theme={null}
    <script src="https://cdn.kodostatus.com/beacon.min.js"></script>
    ```
  </Tab>
</Tabs>

## Quick Start

```javascript theme={null}
import { Beacon } from '@kodo-status/beacon';

const beacon = new Beacon({
  key: 'bpk_your_public_key',  // Get from Dashboard > Settings > Beacon Keys
  service: 'my-frontend',
  environment: 'production'
});

// Errors are captured automatically!
```

## Configuration

```javascript theme={null}
const beacon = new Beacon({
  // Required
  key: 'bpk_your_public_key',

  // Recommended
  service: 'my-app',
  environment: 'production',  // 'development', 'staging', 'production'

  // Optional
  version: '1.2.3',
  debug: false,  // Enable console logging
  maxBreadcrumbs: 50,
  sampleRate: 1.0,  // 0.0 to 1.0

  // User context
  user: {
    id: 'user_123',
    email: 'user@example.com',
    username: 'johndoe'
  }
});
```

## Automatic Error Capture

The SDK automatically captures:

* **Unhandled exceptions** - `window.onerror`
* **Promise rejections** - `unhandledrejection`
* **Console errors** - `console.error` calls
* **Network errors** - Failed fetch/XHR requests

## Manual Error Reporting

```javascript theme={null}
try {
  doSomethingRisky();
} catch (error) {
  beacon.captureError(error, {
    tags: { feature: 'checkout' },
    extra: { cartItems: cart.items.length }
  });
}
```

## Custom Logs

```javascript theme={null}
beacon.log('info', 'User clicked checkout', {
  cartTotal: 99.99,
  itemCount: 3
});

beacon.log('warn', 'Payment retry', { attempt: 2 });
beacon.log('error', 'Payment failed', { reason: 'declined' });
```

## Breadcrumbs

Breadcrumbs help you understand what happened before an error:

```javascript theme={null}
// Automatic breadcrumbs captured:
// - Navigation events
// - Click events
// - Console logs
// - Network requests

// Add custom breadcrumbs
beacon.addBreadcrumb({
  category: 'ui',
  message: 'User opened settings modal',
  level: 'info'
});
```

## User Context

Set user information for error attribution:

```javascript theme={null}
// On login
beacon.setUser({
  id: 'user_123',
  email: 'user@example.com',
  username: 'johndoe'
});

// On logout
beacon.clearUser();
```

## Performance Monitoring

Track page load and custom performance metrics:

```javascript theme={null}
// Automatic Web Vitals tracking
// - Largest Contentful Paint (LCP)
// - First Input Delay (FID)
// - Cumulative Layout Shift (CLS)

// Custom timing
const start = performance.now();
await fetchData();
beacon.timing('api_call', performance.now() - start);
```

## React Integration

```jsx theme={null}
import { BeaconProvider, useBeacon } from '@kodo-status/beacon/react';

function App() {
  return (
    <BeaconProvider
      config={{
        key: 'bpk_your_key',
        service: 'my-react-app'
      }}
    >
      <YourApp />
    </BeaconProvider>
  );
}

// Error boundary included automatically
// Or use the hook:
function MyComponent() {
  const beacon = useBeacon();
  beacon.log('info', 'Component rendered');
}
```

## Filtering Errors

Ignore noisy or irrelevant errors:

```javascript theme={null}
const beacon = new Beacon({
  key: 'bpk_...',
  beforeSend: (event) => {
    // Ignore browser extension errors
    if (event.message?.includes('chrome-extension://')) {
      return null;
    }
    // Ignore specific errors
    if (event.message === 'ResizeObserver loop limit exceeded') {
      return null;
    }
    return event;
  }
});
```

## Getting Your Key

1. Go to **Dashboard > Settings > Beacon Keys**
2. Copy your **Public Key** (`bpk_...`)
3. Use this key in your frontend code

<Warning>
  Never use your API key (`sk_...`) in frontend code. The beacon public key is safe to expose.
</Warning>