npm package: @flowpush/web-sdk
Description: FlowPush browser SDK for Web Push notifications.
Latest version: 0.1.2

# @flowpush/web-sdk

FlowPush browser SDK for Web Push notifications.

This package helps you:

- Register a service worker for push notifications
- Request notification permission
- Subscribe/unsubscribe browser devices
- Identify logged-in users and attach attributes

## Install

```bash
pnpm add @flowpush/web-sdk
```

## Requirements

- HTTPS origin in production (required by Push API and Service Workers)
- A FlowPush app with platform WEB
- VAPID keys configured on that app
- A public service worker file served by your app

## Service Worker Setup

The SDK package builds a worker file at dist/sw.js.

Copy that file into your app public folder as sw.js (or serve it at a custom path):

```bash
cp node_modules/@flowpush/web-sdk/dist/sw.js public/sw.js
```

If you serve it from a different URL, pass serviceWorkerPath when creating the SDK client.

## Quick Start

```ts
import { FlowPush } from "@flowpush/web-sdk"

const flowpush = new FlowPush({
  appKey: "your-app-key",
  apiUrl: "https://your-api-host/api/v1", // optional
  serviceWorkerPath: "/sw.js", // optional
  autoRegister: true, // optional, default true
})

await flowpush.requestPermission()
await flowpush.subscribe()
```

## API

### Constructor

```ts
new FlowPush(options)
```

Options:

- appKey: string (required)
- apiUrl: string (optional)
- serviceWorkerPath: string (optional)
- autoRegister: boolean (optional)

Defaults used by the current implementation:

- apiUrl: https://flow-push-api.vercel.app/api/v1
- serviceWorkerPath: /sw.js
- autoRegister: true

### registerServiceWorker()

```ts
await flowpush.registerServiceWorker()
```

Registers the service worker at serviceWorkerPath.

### requestPermission()

```ts
const permission = await flowpush.requestPermission()
```

Requests browser notification permission and returns NotificationPermission.

### subscribe(options?)

```ts
const result = await flowpush.subscribe({ deviceType: "web" })
```

Flow:

1. Reads VAPID public key from GET /sdk/config
2. Creates browser PushSubscription
3. Syncs subscription to POST /sdk/devices
4. Stores flowpush_device_id in localStorage

The SDK also stores a stable physical id in localStorage as flowpush_physical_id.

### identify(params)

```ts
await flowpush.identify({
  userId: "user_123",
  attributes: {
    plan: "pro",
    locale: "en",
  },
})
```

Calls POST /sdk/identify and links the current device (or physical id) to a user.

### unsubscribe()

```ts
await flowpush.unsubscribe()
```

Unsubscribes from browser push and calls DELETE /sdk/devices with the endpoint.

## Backend Endpoints Expected

The SDK expects these API routes under apiUrl:

- GET /sdk/config
- POST /sdk/devices
- POST /sdk/identify
- DELETE /sdk/devices

Each request includes the x-app-key header.

## Common Issues

- "Notification permission not granted": call requestPermission first and ensure user accepted.
- "Failed to fetch config": verify apiUrl and CORS settings.
- "VAPID key not configured for this App": configure VAPID keys for the WEB app.
- Service worker not found: confirm sw.js is publicly served and serviceWorkerPath matches.

## TypeScript

This package ships type declarations in dist/index.d.ts and dist/index.d.mts.

## License

MIT