npm package: @pwa-reliability/guardian-sdk
Description: Real-time Web Performance Monitoring SDK with Auto-Healing capabilities
Author: PWA Reliability
Latest version: 1.0.1

# @performance-guardian/sdk

> Real-time Web Performance Monitoring with Auto-Healing

Official NPM package for Performance Guardian SDK. Monitor Web Vitals, track errors, and automatically heal performance issues in production.

## Features

✅ **Web Vitals Tracking** - Monitor LCP, FID, CLS, TTFB, INP, FCP
✅ **Error Monitoring** - Track JavaScript errors with stack traces
✅ **Performance Metrics** - Real-time performance analytics
✅ **Auto-Healing** - Automatically fix critical issues (Enterprise)
✅ **Zero Dependencies** - Lightweight and fast
✅ **TypeScript** - Full type safety

## Installation

```bash
npm install @performance-guardian/sdk
# or
yarn add @performance-guardian/sdk
# or
pnpm add @performance-guardian/sdk
```

## Quick Start

### Vanilla JavaScript

```javascript
import { Guardian } from '@performance-guardian/sdk';

const guardian = new Guardian({
  apiUrl: 'https://your-api-url.com',
  siteId: 'your-site-id',
  apiKey: 'your-api-key',
  trackWebVitals: true,
  trackErrors: true,
  autoHeal: false, // Enterprise only
});

guardian.init();
```

### React

```jsx
import { GuardianProvider } from '@performance-guardian/sdk/react';

function App() {
  return (
    <GuardianProvider
      config={{
        apiUrl: 'https://your-api-url.com',
        siteId: 'your-site-id',
        apiKey: 'your-api-key',
      }}
    >
      <YourApp />
    </GuardianProvider>
  );
}
```

### Next.js (App Router)

```tsx
// app/layout.tsx
import { GuardianScript } from '@performance-guardian/sdk/nextjs';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <GuardianScript
          config={{
            apiUrl: process.env.NEXT_PUBLIC_GUARDIAN_URL,
            siteId: process.env.NEXT_PUBLIC_GUARDIAN_SITE_ID,
            apiKey: process.env.NEXT_PUBLIC_GUARDIAN_API_KEY,
          }}
        />
        {children}
      </body>
    </html>
  );
}
```

## Configuration

```typescript
interface GuardianConfig {
  // Required
  apiUrl: string;
  siteId: string;
  apiKey: string;

  // Optional
  trackWebVitals?: boolean; // Default: true
  trackErrors?: boolean; // Default: true
  trackPerformance?: boolean; // Default: true
  trackEvents?: boolean; // Default: true
  autoHeal?: boolean; // Default: false (Enterprise only)
  reportInterval?: number; // Default: 30000 (30 seconds)
  debug?: boolean; // Default: false
  sampleRate?: number; // Default: 1.0 (100%)
}
```

## API

### Guardian Class

```typescript
import { Guardian } from '@performance-guardian/sdk';

const guardian = new Guardian(config);

// Initialize tracking
guardian.init();

// Track custom event
guardian.trackEvent('user_action', { action: 'click', target: 'button' });

// Track custom metric
guardian.trackMetric('custom_metric', 123);

// Report error manually
guardian.reportError(new Error('Something went wrong'), { context: 'user_action' });

// Stop tracking
guardian.stop();
```

### Web Vitals

Automatically tracked:
- **LCP (Largest Contentful Paint)** - Loading performance
- **FID (First Input Delay)** - Interactivity
- **CLS (Cumulative Layout Shift)** - Visual stability
- **TTFB (Time to First Byte)** - Server response time
- **INP (Interaction to Next Paint)** - Responsiveness
- **FCP (First Contentful Paint)** - Initial render

### Error Tracking

Automatically captures:
- Uncaught JavaScript errors
- Unhandled promise rejections
- Stack traces with source maps
- Error context and metadata

### Auto-Healing (Enterprise)

Automatically fixes:
- Service Worker failures
- Cache corruption
- Network timeouts
- Resource loading issues

## Environment Variables

```bash
# .env.local
NEXT_PUBLIC_GUARDIAN_URL=https://pwa-command-center.vercel.app
NEXT_PUBLIC_GUARDIAN_SITE_ID=your-site-id
NEXT_PUBLIC_GUARDIAN_API_KEY=pg_your-api-key
```

## TypeScript

Full TypeScript support included:

```typescript
import type { GuardianConfig, GuardianInstance } from '@performance-guardian/sdk';

const config: GuardianConfig = {
  apiUrl: 'https://your-api-url.com',
  siteId: 'your-site-id',
  apiKey: 'your-api-key',
};

const guardian: GuardianInstance = new Guardian(config);
```

## Browser Support

- Chrome/Edge 90+
- Firefox 88+
- Safari 14+
- Opera 76+

## License

MIT © PWA Reliability

## Support

- 📧 Email: support@pwa-reliability.com
- 🐛 Issues: https://github.com/pwa-reliability/guardian-sdk/issues
- 📖 Docs: https://pwa-reliability.com/docs
- 💬 Discord: https://discord.gg/pwa-reliability

## Changelog

See [CHANGELOG.md](./CHANGELOG.md) for version history.

---

Made with ❤️ by [PWA Reliability](https://pwa-reliability.com)