/** * Snout Push: notifications to iPhone, Android and the web, at `/push/v1`. * * // In the app, once the platform has given you a token: * await db.push.register({ transport: 'apns', token, environment: 'production' }) * // In a browser, with your service worker's registration: * await db.push.subscribeWeb(registration) * // On a server, with the server key (or as a person your policies allow): * await db.push.send({ notification: { title: 'Order shipped' }, userIds: [userId] }) * * Devices, topics, the queue and the delivery log are tables in the project's own database, and * its row-level security decides who may notify whom. Every payload carries the id of its * delivery, so the app can report it received or opened (`deliveryIdOf`, `receipt`). */ import { type Transport } from './http.js'; export declare class PushError extends Error { readonly status: number; constructor(message: string, status: number); } export type PushResult = { data: T; error: null; } | { data: null; error: PushError; }; /** What a notification says, on every transport. */ export interface PushNotification { title?: string; body?: string; /** Delivered to the app beside the notification. */ data?: Record; badge?: number; sound?: string; /** Groups notifications on the device. */ thread?: string; image?: string; /** Where a click on a web notification goes. */ url?: string; /** Shows nothing and wakes the app to handle `data` (never sent to a browser). */ background?: boolean; /** Fields for one transport, merged over what the server builds. */ apns?: Record; fcm?: Record; web?: Record; } export interface SendOptions { notification: PushNotification; /** Exactly one target. */ userIds?: string[]; topic?: string; deviceIds?: string[]; /** A time to send at (paid plans), as an ISO string or a Date. */ sendAt?: string | Date; /** Seconds a provider may hold it for an offline device. */ ttl?: number; priority?: 'high' | 'normal'; /** A newer message with the same key replaces an undelivered older one. */ collapseKey?: string; } export interface RegisterOptions { transport: 'apns' | 'fcm' | 'web'; /** The APNs device token, the FCM registration token, or the Web Push endpoint. */ token: string; /** Web Push only: the subscription's keys. */ p256dh?: string; auth?: string; /** APNs only: which of Apple's environments the build is in. Default `production`. */ environment?: 'production' | 'sandbox'; /** The app's bundle id or FCM app, when a project has more than one. */ app?: string; locale?: string; } export interface MessageStatus { id: number; status: 'queued' | 'sending' | 'sent' | 'partial' | 'failed' | 'refused' | 'cancelled'; detail: string | null; send_at: string | null; created_at: string | null; finished_at: string | null; } /** The data key every delivery's id rides under. */ export declare const DELIVERY_KEY = "snout_push_delivery"; /** * The delivery id in a notification's data, as an app receives it (APNs puts data beside `aps`, * FCM hands data values over as strings, Web Push as the payload's `data`). Null when absent. */ export declare function deliveryIdOf(data: unknown): number | null; /** * In a service worker: turns a push event's payload into the arguments of * `registration.showNotification`. Every browser requires a push to show something. * * self.addEventListener('push', (event) => { * const { title, options } = webNotification(event.data?.json()) * event.waitUntil(self.registration.showNotification(title, options)) * }) */ export declare function webNotification(payload: unknown): { title: string; options: Record; }; /** The browser's `PushSubscription`, as much of it as registering needs. */ interface WebSubscription { endpoint: string; toJSON(): { keys?: { p256dh?: string; auth?: string; }; }; } /** The browser's `ServiceWorkerRegistration`, as much of it as subscribing needs. */ interface WebRegistration { pushManager: { subscribe(options: { userVisibleOnly: boolean; applicationServerKey: Uint8Array; }): Promise; }; } export declare class PushClient { /** @internal */ readonly url: string; private readonly transport; /** Setting and reading the project's own APNs and FCM keys. The server key only. */ readonly credentials: { set(kind: 'apns', body: { topic: string; keys: { p8: string; key_id: string; team_id: string; environment?: 'production' | 'sandbox' | null; }[]; }): Promise>>; set(kind: 'fcm', body: { service_account: string; }): Promise>>; list(): Promise>>>; remove(kind: 'apns' | 'fcm'): Promise>; }; constructor( /** @internal */ url: string, transport: Transport); private call; /** Registers this installation for the signed-in user (or anonymously, where the project allows it). */ register(options: RegisterOptions): Promise>; /** Removes one of the signed-in user's devices, e.g. on sign-out. */ unregister(deviceId: string): Promise>; /** The key a browser subscribes with. */ vapidPublicKey(): Promise>; /** * In a browser: subscribes the service worker to Web Push with the project's key, and * registers the subscription. Ask the user's permission first (`Notification.requestPermission`). */ subscribeWeb(registration: WebRegistration, options?: { locale?: string; }): Promise>; /** Adds the signed-in user to a topic. */ join(topic: string): Promise>; leave(topic: string): Promise>; /** Queues a notification. The project's policies on `push.messages` decide who may. */ send(options: SendOptions): Promise>; /** A message's status, for its sender. */ message(id: number): Promise>; /** * Tells the project a notification reached this device, or was opened. Only these reports * make a delivery "received": a provider's acceptance never does. */ receipt(deliveryId: number, event: 'received' | 'opened'): Promise>; } export {};