npm package: @pushary/sdk
Description: Pushary Web Push Notification SDK - Add push notifications to your website in minutes
Author: Pushary
Latest version: 1.0.9

# @pushary/sdk

Web Push Notification SDK for [Pushary](https://pushary.com) - Add push notifications to your website in minutes.

[![npm version](https://img.shields.io/npm/v/@pushary/sdk.svg)](https://www.npmjs.com/package/@pushary/sdk)

## Features

- Simple API for web push notifications
- TypeScript support with full type definitions
- Works with any framework (React, Vue, Angular, vanilla JS)
- Service worker included
- Click tracking and analytics
- Subscriber segmentation with tags
- iOS Safari support (PWA)

## Installation

```bash
npm install @pushary/sdk
# or
yarn add @pushary/sdk
# or
pnpm add @pushary/sdk
```

### Script Tag

```html
<script src="https://pushary.com/sdk/pushary.js"></script>
```

## Quick Start

### 1. Get your Site Key

Sign up at [pushary.com](https://pushary.com) and create a site to get your site key.

### 2. Add the Service Worker

Copy the service worker file to your public directory:

```bash
cp node_modules/@pushary/sdk/dist/browser/pushary-sw.global.js public/pushary-sw.js
```

### 3. Initialize the SDK

```typescript
import { createPushary } from '@pushary/sdk'

const pushary = createPushary({
  siteKey: 'pk_your_site_key',
  autoPrompt: true,
  debug: true,
  onSubscribe: (subscription) => {
    console.log('Subscribed!', subscription)
  },
})
```

## Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `siteKey` | `string` | **required** | Your Pushary site key (pk_xxx) |
| `apiUrl` | `string` | `'https://pushary.com'` | API endpoint URL |
| `autoPrompt` | `boolean` | `true` | Auto-prompt for permission |
| `promptDelay` | `number` | `3000` | Delay before auto-prompt (ms) |
| `debug` | `boolean` | `false` | Enable debug logging |
| `onSubscribe` | `function` | - | Called on successful subscription |
| `onPermissionDenied` | `function` | - | Called when permission denied |
| `onNotSupported` | `function` | - | Called when push not supported |
| `onNotificationClick` | `function` | - | Called on notification click |

## API

### `createPushary(config): PusharyInstance`

Creates a Pushary instance with the given configuration.

```typescript
const pushary = createPushary({
  siteKey: 'pk_your_site_key',
  debug: true,
})
```

### Methods

#### `promptForPermission(): Promise<PushSubscription | null>`

Request notification permission from the user.

```typescript
const subscription = await pushary.promptForPermission()
```

#### `subscribe(): Promise<PushSubscription | null>`

Subscribe to push notifications (permission must already be granted).

```typescript
const subscription = await pushary.subscribe()
```

#### `unsubscribe(): Promise<void>`

Unsubscribe from push notifications.

```typescript
await pushary.unsubscribe()
```

#### `setExternalId(externalId: string): Promise<void>`

Associate an external ID with the subscriber for targeting.

```typescript
await pushary.setExternalId('user-123')
```

#### `setTags(tags: Record<string, string>): Promise<void>`

Set tags for subscriber segmentation.

```typescript
await pushary.setTags({
  plan: 'premium',
  interests: 'sports,news',
})
```

#### `isSupported(): boolean`

Check if push notifications are supported.

```typescript
if (pushary.isSupported()) {
  // Push is available
}
```

## Authentication

### Client SDK (Browser)

Uses **Site Key** (public prefix):
- Format: `pk_xxxxxxxx`
- Safe to expose in client-side code
- Protected by domain validation

```typescript
const pushary = createPushary({
  siteKey: 'pk_abc123xyz',
})
```

### Server API (Backend)

Uses **Full API Key** (prefix + secret):
- Format: `pk_prefix.sk_secret`
- **NEVER expose in client-side code**
- Use `@pushary/server` package for server-side operations

## Framework Examples

### React

```tsx
import { useEffect } from 'react'
import { createPushary } from '@pushary/sdk'

function App() {
  useEffect(() => {
    const pushary = createPushary({
      siteKey: 'pk_your_site_key',
      autoPrompt: false,
    })

    window.pushary = pushary
  }, [])

  const handleSubscribe = async () => {
    await window.pushary?.promptForPermission()
  }

  return <button onClick={handleSubscribe}>Enable Notifications</button>
}
```

### Next.js

```tsx
'use client'

import { useEffect, useState } from 'react'
import { createPushary, type PusharyInstance } from '@pushary/sdk'

export default function PushNotifications() {
  const [pushary, setPushary] = useState<PusharyInstance | null>(null)

  useEffect(() => {
    const instance = createPushary({
      siteKey: process.env.NEXT_PUBLIC_PUSHARY_SITE_KEY!,
      autoPrompt: false,
    })
    setPushary(instance)
  }, [])

  return (
    <button onClick={() => pushary?.promptForPermission()}>
      Enable Notifications
    </button>
  )
}
```

### Vue 3

```vue
<script setup>
import { onMounted, ref } from 'vue'
import { createPushary } from '@pushary/sdk'

const pushary = ref(null)

onMounted(() => {
  pushary.value = createPushary({
    siteKey: 'pk_your_site_key',
    autoPrompt: false,
  })
})
</script>

<template>
  <button @click="pushary?.promptForPermission()">
    Enable Notifications
  </button>
</template>
```

## TypeScript

Full TypeScript definitions are included:

```typescript
import { 
  createPushary, 
  type PusharyConfig, 
  type PusharyInstance,
  type NotificationData 
} from '@pushary/sdk'

const config: PusharyConfig = {
  siteKey: 'pk_your_site_key',
  onNotificationClick: (url: string, data: NotificationData) => {
    console.log('Clicked:', url, data)
    return true
  },
}

const pushary: PusharyInstance = createPushary(config)
```

## Service Worker Exports

For custom service worker implementations:

```typescript
import {
  handlePush,
  handleNotificationClick,
  handleNotificationClose,
  handleMessage,
} from '@pushary/sdk/service-worker'
```

## Browser Support

- Chrome 50+
- Firefox 44+
- Safari 16+ (macOS & iOS)
- Edge 17+
- Opera 37+

## Plan Limits

| Feature | Free | Starter | Growth | Enterprise |
|---------|------|---------|--------|------------|
| Subscribers | 100 | 5,000 | 25,000 | Unlimited |
| Notifications/month | 500 | 25,000 | 100,000 | Unlimited |
| Sites | 1 | 3 | 10 | Unlimited |
| Data retention | 7 days | 30 days | 90 days | Custom |
| A/B Testing | - | ✓ | ✓ | ✓ |
| API Access | - | ✓ | ✓ | ✓ |
| Priority Support | - | - | ✓ | ✓ |

## License

MIT. See `LICENSE`.

## Links

- [Documentation](https://pushary.com/docs)
- [Dashboard](https://pushary.com/dashboard)
- [Support](mailto:business@ralphnex.com)