npm package: @rkt-labs/observability
Description: A comprehensive TypeScript library for handling analytics, status monitoring, and observability in Next.js applications.
Latest version: 1.0.0

# @rkt-labs/observability

A comprehensive TypeScript library for handling analytics, status monitoring, and observability in Next.js applications.

## Installation

```bash 
npm install @rkt-labs/observability
```

## Features

- 🔍 Multiple Analytics Providers (PostHog, Google Analytics, Vercel)
- 📊 Status Monitoring with BetterStack integration
- ⚛️ React Components for easy implementation
- 📱 Full TypeScript support
- 🔒 Server-side and Client-side components

## Usage

### Analytics Setup

#### PostHog Analytics

```tsx
import { PostHogProvider } from '@rkt-labs/observability/analytics/posthog/client';

export default function App({ children }) {
  return (
    <PostHogProvider>
      {children}
    </PostHogProvider>
  );
}
```

Make sure to set these environment variables:

```env
NEXT_PUBLIC_POSTHOG_KEY=your_posthog_key
NEXT_PUBLIC_POSTHOG_HOST=your_posthog_host
```

#### Google Analytics

```tsx
import { GoogleAnalytics } from '@rkt-labs/observability/analytics/google';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <GoogleAnalytics />
      </body>
    </html>
  );
}
```

### Status Monitoring

The Status component integrates with BetterStack for real-time system status monitoring:

```tsx
import { Status } from '@rkt-labs/observability/status';

export default function StatusIndicator() {
  return (
    <Status 
      apiKey={process.env.BETTERSTACK_API_KEY} 
      url="your-status-page-url" 
    />
  );
}
```

The Status component provides:
- Real-time status monitoring
- Visual status indicators
- Automatic status updates
- Link to status page

Status indicators:
- 🟢 All systems normal (100% uptime)
- 🟡 Partial outage (< 100% uptime)
- 🔴 Degraded performance (0% uptime)
- ⚫ Unable to fetch status

## API Reference

### Status Component

```typescript
type StatusProps = {
  apiKey: string;    // BetterStack API key
  url: string;       // Status page URL
};
```

### PostHog Provider

```typescript
type PostHogProviderProps = {
  children: ReactNode;
};
```

## Configuration

### TypeScript Configuration

Ensure your `tsconfig.json` includes these essential configurations:

```json
{
  "compilerOptions": {
    "jsx": "preserve",
    "moduleResolution": "bundler",
    "strict": true,
    "isolatedModules": true
  }
}
```

### Environment Variables

Required environment variables:

```env
NEXT_PUBLIC_POSTHOG_KEY=your_posthog_key
NEXT_PUBLIC_POSTHOG_HOST=your_posthog_host
BETTERSTACK_API_KEY=your_betterstack_api_key
```

## Requirements

- Next.js 13+ (App Router)
- React 18+
- TypeScript 4.5+

## License

MIT

## Contributing

We welcome contributions! Please feel free to submit a Pull Request.

## Troubleshooting

### TypeScript Compilation Issues

If you encounter TypeScript compilation errors, ensure:

1. Your project's `tsconfig.json` includes:

```json
{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}
```

2. Add package to your TypeScript include paths:

```json
{
  "paths": {
    "@rkt-labs/observability/*": ["./node_modules/@rkt-labs/observability/dist/*"]
  }
}
```

3. If using Next.js, add to your `next.config.js`:

```js
/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: ['@rkt-labs/observability']
}

module.exports = nextConfig
```