@rivium/push-node 0.1.2 → 0.1.4

package/README.md

@@ -200,6 +200,46 @@ await riviumPush.devices.setUserId('device-uuid', 'user-123');
 
 // Delete a device
 await riviumPush.devices.delete('device-uuid');
+
+// Paginated, filtered list (includes inactive devices unless isActive is set)
+const { items, total } = await riviumPush.devices.listPage({
+  platform: 'web',
+  sdkName: 'web',
+  isActive: true,
+  page: 1,
+  limit: 50,
+});
+console.log(items[0]?.sdkName, items[0]?.sdkVersion, items[0]?.appVersion, items[0]?.updatedAt);
+
+// Values you can filter on (app versions, SDK versions, failure reasons)
+const options = await riviumPush.devices.filterOptions();
+
+// Soft-unregister (stops sends, keeps history) and undo it
+await riviumPush.devices.unregister('device-uuid');
+await riviumPush.devices.reactivate('device-uuid');
+```
+
+`list()` is unchanged and still returns a plain array of active devices.
+
+## Delivery Receipts
+
+A send's `success` count means the push service *accepted* the notification.
+Receipts show what happened per device.
+
+```typescript
+const { messageId } = await riviumPush.push.sendToUser({ userId: 'user-123', title: 'Hi', body: 'Hello' });
+const receipts = await riviumPush.receipts.getForMessage(messageId!);
+
+// Paginated receipt log with filters
+const { items } = await riviumPush.receipts.list({ status: 'failed', platform: 'ios', page: 1, limit: 100 });
+
+// Delivery analytics (default range: last 30 days)
+const analytics = await riviumPush.receipts.analytics({
+  startDate: new Date(Date.now() - 7 * 86400_000),
+  endDate: new Date(),
+  bucket: 'day',
+});
+console.log(analytics.totals.deliveryRate, analytics.topFailureReasons);
 ```
 
 ## Templates

package/dist/client.d.ts

@@ -1,4 +1,6 @@
 import { RiviumPushConfig } from './types';
+/** Sent on every request so the backend can attribute traffic to this SDK. */
+export declare const SDK_HEADER_VALUE = "node/0.1.4";
 export declare class HttpClient {
     private apiKey;
     private serverSecret;

package/dist/client.js

@@ -3,10 +3,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RiviumPushError = exports.HttpClient = void 0;
+exports.RiviumPushError = exports.HttpClient = exports.SDK_HEADER_VALUE = void 0;
 const https_1 = __importDefault(require("https"));
 const http_1 = __importDefault(require("http"));
+const version_1 = require("./version");
 const BASE_URL = 'https://push-api.rivium.co';
+/** Sent on every request so the backend can attribute traffic to this SDK. */
+exports.SDK_HEADER_VALUE = `${version_1.SDK_NAME}/${version_1.SDK_VERSION}`;
 class HttpClient {
     constructor(config) {
         if (!config.apiKey) {
@@ -24,7 +27,7 @@ class HttpClient {
         if (query) {
             for (const [k, v] of Object.entries(query)) {
                 if (v !== undefined && v !== null) {
-                    url.searchParams.set(k, String(v));
+                    url.searchParams.set(k, v instanceof Date ? v.toISOString() : String(v));
                 }
             }
         }
@@ -36,6 +39,7 @@ class HttpClient {
             'x-api-key': this.apiKey,
             'x-server-secret': this.serverSecret,
             'Content-Type': 'application/json',
+            'X-Rivium-SDK': exports.SDK_HEADER_VALUE,
         };
         if (payload) {
             headers['Content-Length'] = Buffer.byteLength(payload);

package/dist/index.d.ts

@@ -8,6 +8,7 @@ import { InApp } from './modules/in-app';
 import { ABTesting } from './modules/ab-testing';
 import { Webhooks } from './modules/webhooks';
 import { Analytics } from './modules/analytics';
+import { Receipts } from './modules/receipts';
 import { RiviumPushConfig } from './types';
 export declare class RiviumPush {
     private client;
@@ -31,7 +32,10 @@ export declare class RiviumPush {
     webhooks: Webhooks;
     /** Analytics */
     analytics: Analytics;
+    /** Per-device delivery receipts for messages you have sent. */
+    receipts: Receipts;
     constructor(config: RiviumPushConfig);
 }
 export { RiviumPushError } from './client';
+export { SDK_NAME, SDK_VERSION } from './version';
 export * from './types';

package/dist/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RiviumPushError = exports.RiviumPush = void 0;
+exports.SDK_VERSION = exports.SDK_NAME = exports.RiviumPushError = exports.RiviumPush = void 0;
 const client_1 = require("./client");
 const push_1 = require("./modules/push");
 const devices_1 = require("./modules/devices");
@@ -26,6 +26,7 @@ const in_app_1 = require("./modules/in-app");
 const ab_testing_1 = require("./modules/ab-testing");
 const webhooks_1 = require("./modules/webhooks");
 const analytics_1 = require("./modules/analytics");
+const receipts_1 = require("./modules/receipts");
 class RiviumPush {
     constructor(config) {
         this.client = new client_1.HttpClient(config);
@@ -39,10 +40,14 @@ class RiviumPush {
         this.abTesting = new ab_testing_1.ABTesting(this.client);
         this.webhooks = new webhooks_1.Webhooks(this.client);
         this.analytics = new analytics_1.Analytics(this.client);
+        this.receipts = new receipts_1.Receipts(this.client);
     }
 }
 exports.RiviumPush = RiviumPush;
 var client_2 = require("./client");
 Object.defineProperty(exports, "RiviumPushError", { enumerable: true, get: function () { return client_2.RiviumPushError; } });
+var version_1 = require("./version");
+Object.defineProperty(exports, "SDK_NAME", { enumerable: true, get: function () { return version_1.SDK_NAME; } });
+Object.defineProperty(exports, "SDK_VERSION", { enumerable: true, get: function () { return version_1.SDK_VERSION; } });
 // Re-export types
 __exportStar(require("./types"), exports);

package/dist/modules/devices.d.ts

@@ -1,5 +1,5 @@
 import { HttpClient } from '../client';
-import { Device } from '../types';
+import { Device, DeviceFilterOptions, DeviceListFilters, Paginated } from '../types';
 export declare class Devices {
     private client;
     constructor(client: HttpClient);
@@ -7,6 +7,37 @@ export declare class Devices {
      * List all registered devices.
      */
     list(): Promise<Device[]>;
+    /**
+     * List devices one page at a time, with filters. Unlike `list()`, this
+     * includes inactive (unregistered) devices unless you pass `isActive`.
+     *
+     * @example
+     * ```ts
+     * const { items, total } = await rivium.devices.listPage({ platform: 'web', sdkName: 'web', page: 1, limit: 50 });
+     * ```
+     */
+    listPage(filters?: DeviceListFilters): Promise<Paginated<Device>>;
+    /**
+     * Distinct app versions, SDK name/version pairs and recent failure reasons,
+     * with counts — the values `listPage()` can filter on.
+     */
+    filterOptions(): Promise<DeviceFilterOptions>;
+    /**
+     * Soft-unregister a device: it stops receiving sends but keeps its row and
+     * receipt history. The device is reactivated by `reactivate()` or by its
+     * SDK's next register(). Use `delete()` to remove it entirely.
+     */
+    unregister(deviceId: string): Promise<{
+        deviceId: string;
+        isActive: false;
+    }>;
+    /**
+     * Reactivate a soft-unregistered device.
+     */
+    reactivate(deviceId: string): Promise<{
+        deviceId: string;
+        isActive: true;
+    }>;
     /**
      * Delete a device by its deviceId.
      */

package/dist/modules/devices.js

@@ -11,6 +11,41 @@ class Devices {
     async list() {
         return this.client.get('/devices');
     }
+    /**
+     * List devices one page at a time, with filters. Unlike `list()`, this
+     * includes inactive (unregistered) devices unless you pass `isActive`.
+     *
+     * @example
+     * ```ts
+     * const { items, total } = await rivium.devices.listPage({ platform: 'web', sdkName: 'web', page: 1, limit: 50 });
+     * ```
+     */
+    async listPage(filters = {}) {
+        const { page, limit, ...rest } = filters;
+        // The backend only paginates when page or limit is present.
+        return this.client.get('/devices', { page: page ?? 1, limit, ...rest });
+    }
+    /**
+     * Distinct app versions, SDK name/version pairs and recent failure reasons,
+     * with counts — the values `listPage()` can filter on.
+     */
+    async filterOptions() {
+        return this.client.get('/devices/filter-options');
+    }
+    /**
+     * Soft-unregister a device: it stops receiving sends but keeps its row and
+     * receipt history. The device is reactivated by `reactivate()` or by its
+     * SDK's next register(). Use `delete()` to remove it entirely.
+     */
+    async unregister(deviceId) {
+        return this.client.post(`/devices/${encodeURIComponent(deviceId)}/unregister`);
+    }
+    /**
+     * Reactivate a soft-unregistered device.
+     */
+    async reactivate(deviceId) {
+        return this.client.post(`/devices/${encodeURIComponent(deviceId)}/reactivate`);
+    }
     /**
      * Delete a device by its deviceId.
      */

package/dist/modules/receipts.d.ts

@@ -0,0 +1,61 @@
+import { HttpClient } from '../client';
+import { DeliveryReceipt, MessageDeliveryStats, Paginated, ReceiptAnalytics, ReceiptAnalyticsOptions, ReceiptListFilters, ReceiptListItem } from '../types';
+/**
+ * Delivery receipts — what actually happened to a notification, per device.
+ *
+ * A send returns `success` / `failed`, but those count what the push service
+ * *accepted*: APNs, FCM and Web Push confirm acceptance, never delivery.
+ * Receipts carry the rest of the story — which device, over which transport,
+ * why it failed, and whether the device confirmed receipt.
+ *
+ * Receipts are written for targeted sends (`sendToUser`, `sendToDevices`).
+ * Broadcasts record an aggregated per-platform breakdown on the message
+ * instead, since a row per device does not scale to a large audience.
+ */
+export declare class Receipts {
+    private client;
+    constructor(client: HttpClient);
+    /**
+     * Get every receipt for a message.
+     *
+     * @param messageId `messageId` from the SendResult of the original send.
+     */
+    getForMessage(messageId: string): Promise<DeliveryReceipt[]>;
+    /**
+     * Get delivery/open/click rates for one message.
+     */
+    getMessageStats(messageId: string): Promise<MessageDeliveryStats>;
+    /**
+     * Get click counts per notification action button for one message.
+     */
+    getActionStats(messageId: string): Promise<{
+        actionId: string;
+        count: number;
+    }[]>;
+    /**
+     * Get recent receipts for one device — useful for answering
+     * "did this user receive anything?".
+     */
+    getForDevice(deviceId: string, limit?: number): Promise<DeliveryReceipt[]>;
+    /**
+     * Get aggregate delivery stats for the project over a date range.
+     */
+    getStats(startDate: Date | string, endDate: Date | string): Promise<MessageDeliveryStats>;
+    /**
+     * Page through the receipt log for your app, newest first. All filters are
+     * optional exact matches; `hasError: true` returns failures that carry a
+     * reason without you knowing the reason strings.
+     *
+     * @example
+     * ```ts
+     * const { items, total } = await rivium.receipts.list({ platform: 'ios', status: 'failed', limit: 100 });
+     * ```
+     */
+    list(filters?: ReceiptListFilters): Promise<Paginated<ReceiptListItem>>;
+    /**
+     * Delivery analytics for a date range (default: the last 30 days): totals,
+     * per-platform, per-transport and per-SDK-version breakdowns, a timeseries
+     * bucketed by day or hour, and the top failure reasons.
+     */
+    analytics(options?: ReceiptAnalyticsOptions): Promise<ReceiptAnalytics>;
+}

package/dist/modules/receipts.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Receipts = void 0;
+/**
+ * Delivery receipts — what actually happened to a notification, per device.
+ *
+ * A send returns `success` / `failed`, but those count what the push service
+ * *accepted*: APNs, FCM and Web Push confirm acceptance, never delivery.
+ * Receipts carry the rest of the story — which device, over which transport,
+ * why it failed, and whether the device confirmed receipt.
+ *
+ * Receipts are written for targeted sends (`sendToUser`, `sendToDevices`).
+ * Broadcasts record an aggregated per-platform breakdown on the message
+ * instead, since a row per device does not scale to a large audience.
+ */
+class Receipts {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Get every receipt for a message.
+     *
+     * @param messageId `messageId` from the SendResult of the original send.
+     */
+    async getForMessage(messageId) {
+        return this.client.get(`/receipts/message/${encodeURIComponent(messageId)}`);
+    }
+    /**
+     * Get delivery/open/click rates for one message.
+     */
+    async getMessageStats(messageId) {
+        return this.client.get(`/receipts/message/${encodeURIComponent(messageId)}/stats`);
+    }
+    /**
+     * Get click counts per notification action button for one message.
+     */
+    async getActionStats(messageId) {
+        return this.client.get(`/receipts/message/${encodeURIComponent(messageId)}/actions`);
+    }
+    /**
+     * Get recent receipts for one device — useful for answering
+     * "did this user receive anything?".
+     */
+    async getForDevice(deviceId, limit) {
+        return this.client.get(`/receipts/device/${encodeURIComponent(deviceId)}`, { limit });
+    }
+    /**
+     * Get aggregate delivery stats for the project over a date range.
+     */
+    async getStats(startDate, endDate) {
+        return this.client.get('/receipts/stats', {
+            startDate: startDate instanceof Date ? startDate.toISOString() : startDate,
+            endDate: endDate instanceof Date ? endDate.toISOString() : endDate,
+        });
+    }
+    /**
+     * Page through the receipt log for your app, newest first. All filters are
+     * optional exact matches; `hasError: true` returns failures that carry a
+     * reason without you knowing the reason strings.
+     *
+     * @example
+     * ```ts
+     * const { items, total } = await rivium.receipts.list({ platform: 'ios', status: 'failed', limit: 100 });
+     * ```
+     */
+    async list(filters = {}) {
+        return this.client.get('/receipts', { ...filters });
+    }
+    /**
+     * Delivery analytics for a date range (default: the last 30 days): totals,
+     * per-platform, per-transport and per-SDK-version breakdowns, a timeseries
+     * bucketed by day or hour, and the top failure reasons.
+     */
+    async analytics(options = {}) {
+        return this.client.get('/receipts/analytics', { ...options });
+    }
+}
+exports.Receipts = Receipts;

package/dist/types.d.ts

@@ -4,6 +4,13 @@ export interface RiviumPushConfig {
     /** Server secret for server-side authentication (rv_srv_xxx) - required for all server operations */
     serverSecret: string;
 }
+/** Page-numbered list response. */
+export interface Paginated<T> {
+    items: T[];
+    total: number;
+    page: number;
+    limit: number;
+}
 export interface PaginationParams {
     limit?: number;
     offset?: number;
@@ -17,6 +24,141 @@ export interface SendResult {
     failed: number;
     reason?: 'no_recipients';
     billing?: BillingInfo;
+    /**
+     * Id of the message this send created. Use it to fetch delivery receipts
+     * later — `success` only means the push service accepted the notification,
+     * not that any device received it.
+     */
+    messageId?: string;
+}
+/** Which transport carried a notification to a device. */
+export type DeliveryTransport = 'apns' | 'voip' | 'webpush' | 'pn';
+export type ReceiptStatus = 'sent' | 'delivered' | 'opened' | 'clicked' | 'failed' | 'dismissed';
+export interface DeliveryReceipt {
+    id: string;
+    messageId: string;
+    deviceId: string;
+    userId?: string;
+    platform?: string;
+    /** `sent` = accepted by the transport; `delivered` = confirmed by the device. */
+    status: ReceiptStatus;
+    transport?: DeliveryTransport;
+    /** The push service's own id — APNs `apns-id`. Quote it when escalating. */
+    providerMessageId?: string;
+    /** Failure reason, e.g. 'Unregistered', 'Gone', 'BadDeviceToken'. */
+    error?: string;
+    sentAt: string;
+    deliveredAt?: string;
+    openedAt?: string;
+    clickedAt?: string;
+    /** SDK that registered the device (send-time snapshot, device fallback). */
+    sdkName?: string | null;
+    sdkVersion?: string | null;
+    appVersion?: string | null;
+}
+/** One row of `receipts.list()`. */
+export interface ReceiptListItem {
+    id: string;
+    messageId: string;
+    messageTitle: string;
+    deviceId: string;
+    userId: string | null;
+    status: ReceiptStatus;
+    platform: string | null;
+    transport: string | null;
+    providerMessageId: string | null;
+    error: string | null;
+    actionId: string | null;
+    sentAt: string;
+    deliveredAt: string | null;
+    openedAt: string | null;
+    clickedAt: string | null;
+    /** Send-time snapshot, falling back to the device's current values; null = unknown. */
+    sdkName: string | null;
+    sdkVersion: string | null;
+    appVersion: string | null;
+}
+export interface ReceiptListFilters {
+    /** 1-based page (default 1). */
+    page?: number;
+    /** Page size (default 50, max 200). */
+    limit?: number;
+    platform?: Platform;
+    status?: ReceiptStatus;
+    transport?: DeliveryTransport;
+    /** Exact failure reason, e.g. 'Unregistered'. */
+    error?: string;
+    /** true = only failed receipts with a reason; false = only without. */
+    hasError?: boolean;
+    userId?: string;
+    deviceId?: string;
+    messageId?: string;
+    startDate?: Date | string;
+    endDate?: Date | string;
+}
+export interface ReceiptCounts {
+    total: number;
+    sent: number;
+    delivered: number;
+    opened: number;
+    clicked: number;
+    failed: number;
+    /**
+     * Receipts the device itself acked. iOS can only confirm with a Notification
+     * Service Extension, so a low iOS delivery rate is expected without one.
+     */
+    deliveryConfirmedCount: number;
+    deliveryRate: number;
+    openRate: number;
+    clickRate: number;
+    failureRate: number;
+}
+export interface ReceiptAnalyticsOptions {
+    /** Default: 30 days before endDate. */
+    startDate?: Date | string;
+    /** Default: now. */
+    endDate?: Date | string;
+    /** Default 'day'. */
+    bucket?: 'day' | 'hour';
+}
+export interface ReceiptAnalytics {
+    startDate: string;
+    endDate: string;
+    bucket: 'day' | 'hour';
+    totals: ReceiptCounts;
+    /** `needsNse` is true for iOS: background delivery is only confirmed with a Notification Service Extension. */
+    byPlatform: (ReceiptCounts & {
+        platform: string;
+        needsNse: boolean;
+    })[];
+    timeseries: (ReceiptCounts & {
+        bucket: string;
+        platform: string;
+    })[];
+    topFailureReasons: {
+        platform: string;
+        error: string;
+        count: number;
+    }[];
+    byTransport: (ReceiptCounts & {
+        transport: string;
+    })[];
+    /** 'unknown' when neither the receipt nor the device recorded an SDK. */
+    bySdkVersion: (ReceiptCounts & {
+        sdkName: string;
+        sdkVersion: string;
+    })[];
+}
+export interface MessageDeliveryStats {
+    total: number;
+    sent: number;
+    delivered: number;
+    opened: number;
+    clicked: number;
+    failed: number;
+    deliveryRate: number;
+    openRate: number;
+    clickRate: number;
 }
 export interface NotificationAction {
     id: string;
@@ -81,7 +223,47 @@ export interface Device {
     appIdentifier?: string;
     userId?: string;
     metadata?: Record<string, any>;
+    isActive?: boolean;
+    appVersion?: string | null;
+    /** SDK that last registered the device, e.g. 'web', 'ios', 'flutter'. */
+    sdkName?: string | null;
+    sdkVersion?: string | null;
     createdAt: string;
+    /** Last registration/update; used as "last seen". */
+    updatedAt?: string;
+}
+export interface DeviceListFilters {
+    /** 1-based page (default 1). */
+    page?: number;
+    /** Page size (default 50, max 200). */
+    limit?: number;
+    platform?: Platform;
+    isActive?: boolean;
+    userId?: string;
+    appVersion?: string;
+    sdkName?: string;
+    sdkVersion?: string;
+    /** Substring match on deviceId or userId. */
+    search?: string;
+    lastSeenBefore?: Date | string;
+    lastSeenAfter?: Date | string;
+    /** The device's most recent receipt failure reason, e.g. 'Unregistered'. */
+    failureReason?: string;
+}
+export interface DeviceFilterOptions {
+    appVersions: {
+        appVersion: string;
+        count: number;
+    }[];
+    sdks: {
+        sdkName: string;
+        sdkVersion: string;
+        count: number;
+    }[];
+    failureReasons: {
+        error: string;
+        count: number;
+    }[];
 }
 export interface CreateTemplateOptions {
     name: string;

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const SDK_NAME = "node";
+export declare const SDK_VERSION = "0.1.4";

package/dist/version.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDK_VERSION = exports.SDK_NAME = void 0;
+// AUTO-GENERATED by scripts/gen-version.mjs from package.json. Do not edit.
+exports.SDK_NAME = 'node';
+exports.SDK_VERSION = '0.1.4';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rivium/push-node",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "repository": {
     "type": "git",
     "url": "https://github.com/Rivium-co/rivium-push-nodejs-sdk.git"
@@ -9,14 +9,16 @@
   "bugs": {
     "url": "https://github.com/Rivium-co/rivium-push-nodejs-sdk/issues"
   },
-  "description": "RiviumPush Node.js SDK \u2014 server-side push notifications, inbox, in-app messages, and more",
+  "description": "RiviumPush Node.js SDK — server-side push notifications, inbox, in-app messages, and more",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist"
   ],
   "scripts": {
+    "prebuild": "node scripts/gen-version.mjs",
     "build": "tsc",
+    "test": "npm run build && node --test test/*.test.js",
     "prepublishOnly": "npm run build"
   },
   "keywords": [