@rivium/push-node 0.1.1 → 0.1.3

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,6 +32,8 @@ 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';

package/dist/index.js

@@ -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,6 +40,7 @@ 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;

package/dist/modules/receipts.d.ts

@@ -0,0 +1,44 @@
+import { HttpClient } from '../client';
+import { DeliveryReceipt, MessageDeliveryStats } 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>;
+}

package/dist/modules/receipts.js

@@ -0,0 +1,57 @@
+"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,
+        });
+    }
+}
+exports.Receipts = Receipts;

package/dist/modules/segments.d.ts

@@ -1,5 +1,5 @@
 import { HttpClient } from '../client';
-import { Segment, CreateSegmentOptions, UpdateSegmentOptions, Device } from '../types';
+import { Segment, CreateSegmentOptions, UpdateSegmentOptions, Device, SegmentPreviewOptions, SegmentPreviewResult } from '../types';
 export declare class Segments {
     private client;
     constructor(client: HttpClient);
@@ -41,4 +41,21 @@ export declare class Segments {
     recalculateAll(): Promise<{
         success: boolean;
     }>;
+    /**
+     * Preview a set of filters without saving. Returns the total match count
+     * plus a small sample of matching devices — useful for validating filters
+     * before creating a segment.
+     *
+     * @example
+     * ```ts
+     * const { count, preview } = await rivium.segments.preview({
+     *   filters: [
+     *     { field: 'platform', operator: 'equals', value: 'ios' },
+     *     { field: 'metadata.plan', operator: 'equals', value: 'premium' },
+     *   ],
+     * });
+     * console.log(`${count} devices match`);
+     * ```
+     */
+    preview(options?: SegmentPreviewOptions): Promise<SegmentPreviewResult>;
 }

package/dist/modules/segments.js

@@ -53,5 +53,26 @@ class Segments {
     async recalculateAll() {
         return this.client.post('/segments/recalculate-all');
     }
+    /**
+     * Preview a set of filters without saving. Returns the total match count
+     * plus a small sample of matching devices — useful for validating filters
+     * before creating a segment.
+     *
+     * @example
+     * ```ts
+     * const { count, preview } = await rivium.segments.preview({
+     *   filters: [
+     *     { field: 'platform', operator: 'equals', value: 'ios' },
+     *     { field: 'metadata.plan', operator: 'equals', value: 'premium' },
+     *   ],
+     * });
+     * console.log(`${count} devices match`);
+     * ```
+     */
+    async preview(options = {}) {
+        const { limit, ...body } = options;
+        const path = limit ? `/segments/preview?limit=${limit}` : '/segments/preview';
+        return this.client.post(path, body);
+    }
 }
 exports.Segments = Segments;

package/dist/types.d.ts

@@ -17,6 +17,44 @@ 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;
+}
+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;
@@ -112,10 +150,11 @@ export interface Template {
     createdAt: string;
     updatedAt: string;
 }
+export type SegmentFilterOperator = 'equals' | 'not_equals' | 'contains' | 'not_contains' | 'greater_than' | 'less_than' | 'in' | 'not_in' | 'exists';
 export interface SegmentFilter {
     field: string;
-    operator: 'equals' | 'contains' | 'starts_with' | 'in' | 'gt' | 'lt' | 'between';
-    value: string | number | string[];
+    operator: SegmentFilterOperator;
+    value: string | number | boolean | string[];
 }
 export interface CreateSegmentOptions {
     name: string;
@@ -135,6 +174,23 @@ export interface Segment {
     createdAt: string;
     updatedAt: string;
 }
+export interface SegmentPreviewOptions {
+    filters?: SegmentFilter[];
+    /** Number of sample devices to return (max 50, default 20). */
+    limit?: number;
+}
+export interface SegmentPreviewResult {
+    /** Total number of devices matching the filters. */
+    count: number;
+    /** Small sample of matching devices (up to `limit`). */
+    preview: Array<{
+        deviceId: string;
+        platform: string;
+        userId: string | null;
+        topics: string[] | null;
+        metadata: Record<string, any> | null;
+    }>;
+}
 export interface CreateScheduledOptions {
     title: string;
     body: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rivium/push-node",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "repository": {
     "type": "git",
     "url": "https://github.com/Rivium-co/rivium-push-nodejs-sdk.git"