SDK Reference
Browser package: @gesher/sdk
The SDK never holds your Gesher API key. It requests notification permission, registers your service worker, creates a PushSubscription, and POSTs the result to your backend URLs.
Installation
npm install @gesher/sdkimport { GesherClient } from '@gesher/sdk'GesherClient constructor
new GesherClient(config: GesherConfig)| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
subscribeEndpoint | string | Yes | — | URL of your backend proxy for subscribe |
unsubscribeEndpoint | string | Yes | — | URL of your backend proxy for unsubscribe |
vapidPublicKey | string | No | (see below) | VAPID public key for PushManager.subscribe |
vapidKeyEndpoint | string | No | https://api.gesher.pro/vapid-key | URL used to fetch the key when vapidPublicKey is omitted |
serviceWorkerPath | string | No | /gesher-sw.js | Script URL passed to navigator.serviceWorker.register |
serviceWorkerScope | string | No | / | Registration scope |
If vapidPublicKey is omitted, the client fetches the key from vapidKeyEndpoint. The Gesher API returns { "publicKey": "..." }. If you rely on auto-fetch, ensure your deployed API and SDK versions agree on the JSON field name; setting vapidPublicKey explicitly (copy the value from GET /vapid-key) is the most reliable approach.
Methods
| Method | Returns | Description |
|---|---|---|
subscribe(userId) | Promise<GesherResult> | Permission → service worker → push subscription → POST to subscribeEndpoint |
unsubscribe(userId?) | Promise<GesherResult> | Unsubscribe in the browser → POST to unsubscribeEndpoint with { userId, endpoint } |
getState() | Promise<GesherSubscriptionState> | 'subscribed' | 'unsubscribed' | 'denied' | 'unsupported' |
isSubscribed() | Promise<boolean> | true if getState() is 'subscribed' |
unsubscribe(userId?) uses the last userId passed to subscribe when userId is omitted.
Types
interface GesherResult {
ok: boolean
error?: string
}
type GesherSubscriptionState = 'subscribed' | 'unsubscribed' | 'denied' | 'unsupported'
interface GesherSubscriptionPayload {
userId: string
subscription: { endpoint: string; keys: { p256dh: string; auth: string } }
}
interface GesherUnsubscribePayload {
userId: string
endpoint: string
}GesherNotificationPayload exists in the package for typing payloads you send server-side to /notify (not used by the browser client).
Service worker file
Ship the template from @gesher/sdk/sw (file gesher-sw.js) on your origin. See Service Worker.