npm package: @notifyon/web
Description: NotifyOn Web SDK
Author: NotifyOn
Latest version: 0.1.4

# @notifyon/web

Browser SDK for NotifyOn - Get real-time sound and push notifications when your long-running tasks complete.

## Installation

### NPM / Yarn / PNPM

```bash
npm install @notifyon/web
# or
yarn add @notifyon/web
# or
pnpm add @notifyon/web
```

### CDN

```html
<!-- UMD build -->
<script src="https://unpkg.com/@notifyon/web"></script>

<!-- or from jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/@notifyon/web"></script>
```

## Usage

### ES Modules (React, Vue, Angular, etc.)

```javascript
import { connect } from '@notifyon/web';

// Start listening for notifications
const notifyon = connect({ 
  publicKey: 'pk_your_public_key',
  userId: 'user_123'
});
```

### CommonJS

```javascript
const { connect } = require('@notifyon/web');

const notifyon = connect({
  publicKey: 'pk_your_public_key',
  userId: 'user_123'
});
```

### Script Tag (Vanilla HTML)

```html
<!DOCTYPE html>
<html>
<head>
  <script src="https://unpkg.com/@notifyon/web"></script>
</head>
<body>
  <script>
    // Access via global notifyon object
    const instance = notifyon.connect({
      publicKey: 'pk_your_public_key',
      userId: 'user_123'
    });
  </script>
</body>
</html>
```

### React Example

```jsx
import { useEffect } from 'react';
import { connect } from '@notifyon/web';

function App() {
  useEffect(() => {
    const notifyon = connect({
      publicKey: 'pk_your_public_key',
      userId: 'user_123'
    });

    return () => notifyon.destroy();
  }, []);
  
  return <div>Your app content...</div>;
}
```

### Vue 3 Example

```vue
<template>
  <div>Your app content...</div>
</template>

<script setup>
import { onMounted, onUnmounted } from 'vue';
import { connect } from '@notifyon/web';

let notifyon = null;

onMounted(() => {
  notifyon = connect({
    publicKey: 'pk_your_public_key',
    userId: 'user_123'
  });
});

onUnmounted(() => {
  notifyon?.destroy();
});
</script>
```

## API Reference

### `connect(config)`

Connects to NotifyOn and starts listening for notifications.

**Parameters:**
- `publicKey` (required): Your NotifyOn public key from the dashboard
- `userId` (required): The user ID to listen for notifications

**Returns:** NotifyOn instance with `destroy()` method for cleanup

## TypeScript Support

```typescript
import { connect } from '@notifyon/web';
import type { NotifyOnWebConfig } from '@notifyon/web';

const config: NotifyOnWebConfig = {
  publicKey: 'pk_your_public_key',
  userId: 'user_123'
};

const notifyon = connect(config);

// Cleanup when done
notifyon.destroy();
```

## Features

- **Automatic Connection**: Connects immediately when instantiated
- **Auto-Reconnection**: Automatically reconnects if connection is lost
- **Sound Alerts**: Plays a pleasant, non-disruptive notification sound in the browser
- **Push Notifications**: Native browser push notifications with automatic permission handling
- **Smart Channel Detection**: Automatically handles sound, push, or both based on server preferences
- **Zero Configuration**: Works out of the box with just public key and user ID

## Configuration Options

```javascript
connect({
  publicKey: 'pk_your_public_key',    // Required - get from NotifyOn dashboard
  userId: 'user_123'                  // Required - your user's ID
});
```

## Browser Compatibility

- All modern browsers (Chrome, Firefox, Safari, Edge)
- Web Audio API for notification sounds
- Automatic reconnection on network issues

## License

MIT