irontelemetry-js/README.md

<p align="center">
  <a href="https://irontelemetry.com">
    <img src="https://irontelemetry.com/logo.png" alt="IronTelemetry" width="120" />
  </a>
</p>

<h1 align="center">IronTelemetry SDK for JavaScript/TypeScript</h1>

<p align="center">
  <strong>Error monitoring and crash reporting for modern applications</strong>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@ironservices/telemetry"><img src="https://img.shields.io/npm/v/@ironservices/telemetry.svg" alt="npm version"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
</p>

<p align="center">
  <a href="https://irontelemetry.com">Website</a> •
  <a href="https://irontelemetry.com/docs">Documentation</a> •
  <a href="https://irontelemetry.com/docs/js">JavaScript Guide</a> •
  <a href="https://git.marketally.com/ironservices">GitHub</a>
</p>

---

**IronTelemetry** helps you capture exceptions, track user journeys, and get actionable insights to fix issues faster. Built for developers who want simple, powerful error monitoring without the complexity.

## Features

- **Exception Capture** - Automatically capture and report exceptions with full stack traces
- **Journey Tracking** - Understand what users did before an error occurred
- **Breadcrumbs** - Add context with custom breadcrumbs and metadata
- **Source Maps** - See original source code in stack traces
- **Lightweight** - Minimal footprint, no impact on performance
- **TypeScript First** - Full TypeScript support with type definitions

## Installation

```bash
npm install @ironservices/telemetry
# or
yarn add @ironservices/telemetry
# or
pnpm add @ironservices/telemetry
```

## Quick Start

### Initialize the SDK

```typescript
import IronTelemetry from '@ironservices/telemetry';

IronTelemetry.init('https://pk_live_xxx@irontelemetry.com');
```

### Capture Exceptions

```typescript
try {
  doSomething();
} catch (error) {
  IronTelemetry.captureException(error);
  throw error;
}

// Or use the extension method
try {
  doSomething();
} catch (error) {
  throw error.capture();
}
```

### Track User Journeys

```typescript
// Start a journey
const journey = IronTelemetry.startJourney('checkout', { userId: 'user-123' });

// Add steps
journey.step('add_to_cart', { productId: 'prod-456' });
journey.step('enter_shipping');
journey.step('enter_payment');

// Complete or fail
journey.complete(); // or journey.fail('Payment declined');
```

### Add Breadcrumbs

```typescript
IronTelemetry.addBreadcrumb({
  category: 'user',
  message: 'Clicked checkout button',
  level: 'info',
});
```

### Set User Context

```typescript
IronTelemetry.setUser({
  id: 'user-123',
  email: 'user@example.com',
  name: 'John Doe',
});
```

## Framework Integrations

### Express.js

```typescript
import express from 'express';
import IronTelemetry from '@ironservices/telemetry';

const app = express();

// Add error handler
app.use(IronTelemetry.express.errorHandler());
```

### React

```typescript
import { ErrorBoundary } from '@ironservices/telemetry/react';

function App() {
  return (
    <ErrorBoundary fallback={<ErrorPage />}>
      <MyApp />
    </ErrorBoundary>
  );
}
```

## Configuration Options

```typescript
IronTelemetry.init('https://pk_live_xxx@irontelemetry.com', {
  environment: 'production',
  release: '1.0.0',
  sampleRate: 1.0,
  beforeSend: (event) => {
    // Filter or modify events
    return event;
  },
});
```

## Documentation

For complete documentation, visit [irontelemetry.com/docs](https://irontelemetry.com/docs).

## Other SDKs

| Platform | Package |
|----------|---------|
| .NET | [IronTelemetry.Client](https://git.marketally.com/ironservices/irontelemetry-dotnet) |
| Python | [irontelemetry](https://git.marketally.com/ironservices/irontelemetry-python) |
| Go | [irontelemetry-go](https://git.marketally.com/ironservices/irontelemetry-go) |
| Java | [irontelemetry-java](https://git.marketally.com/ironservices/irontelemetry-java) |
| Rust | [irontelemetry](https://git.marketally.com/ironservices/irontelemetry-rust) |

## Support

- **Documentation**: [irontelemetry.com/docs](https://irontelemetry.com/docs)
- **Email**: dev@ironservices.io
- **Issues**: [git.marketally.com/ironservices/irontelemetry-js/issues](https://git.marketally.com/ironservices/irontelemetry-js/issues)

## License

MIT License - see [LICENSE](LICENSE) for details.