@rivium/push-node 0.1.0 → 0.1.2

package/README.md

@@ -5,13 +5,13 @@ Server-side SDK for [RiviumPush](https://rivium.co) — push notifications, inbo
 ## Installation
 
 ```bash
-npm install @rivium-push/node
+npm install @rivium/push-node
 ```
 
 ## Quick Start
 
 ```typescript
-import { RiviumPush } from '@rivium-push/node';
+import { RiviumPush } from '@rivium/push-node';
 
 const riviumPush = new RiviumPush({
   apiKey: 'rv_live_xxxxxxxxxxxxxxxxxxxxx',
@@ -75,6 +75,41 @@ await riviumPush.push.broadcast({
 });
 ```
 
+### Handling the Response
+
+Every send returns `{ success, failed, reason? }`. When the target had **zero registered devices** the message is not attempted and `reason` is set to `'no_recipients'` — distinct from a real delivery failure:
+
+```typescript
+const result = await riviumPush.push.sendToUser({
+  userId: 'user-123',
+  title: 'Your order shipped',
+  body: 'Track it from the app',
+});
+
+if (result.reason === 'no_recipients') {
+  // User has no device registered with Rivium Push.
+  // Fall back to email / SMS, mark them as push-unreachable, etc.
+} else if (result.failed > 0) {
+  // Real delivery failure on at least one device.
+}
+```
+
+### App Identifier
+
+If your project has multiple apps (e.g. a shopping app and a chat app), use `appIdentifier` to target a specific app. This is the bundle ID / package name of the app (e.g. `com.myapp.ios`).
+
+```typescript
+// Send only to a specific app on the device
+await riviumPush.push.sendToUser({
+  userId: 'user-123',
+  title: 'New Order',
+  body: 'Your order is ready',
+  appIdentifier: 'com.myshop.app', // only this app receives it
+});
+```
+
+> **Note:** `appIdentifier` is optional. If not set, the notification is sent to all apps registered under your project. Most projects have a single app, so you don't need to set it.
+
 ### Rich Notifications
 
 ```typescript
@@ -128,6 +163,16 @@ await riviumPush.inbox.sendToUsers({
   },
 });
 
+// Send to a specific app only
+await riviumPush.inbox.sendToUser({
+  userId: 'user-123',
+  appIdentifier: 'com.myshop.app',
+  content: {
+    title: 'Order Update',
+    body: 'Your order has shipped',
+  },
+});
+
 // Broadcast to all
 await riviumPush.inbox.broadcast({
   content: {
@@ -224,7 +269,14 @@ await riviumPush.scheduled.cancel(scheduled.id);
 const webhook = await riviumPush.webhooks.create({
   name: 'Order Events',
   url: 'https://example.com/webhooks/rivium-push',
-  events: ['message.delivered', 'message.opened', 'message.clicked'],
+  events: [
+    'message.sent',
+    'message.delivered',
+    'message.failed',
+    'message.no_recipients',
+    'message.opened',
+    'message.clicked',
+  ],
   secret: 'my-secret-key',
 });
 
@@ -306,7 +358,7 @@ await riviumPush.inApp.activate('your-app-id', message.id);
 ## Error Handling
 
 ```typescript
-import { RiviumPush, RiviumPushError } from '@rivium-push/node';
+import { RiviumPush, RiviumPushError } from '@rivium/push-node';
 
 try {
   await riviumPush.push.sendToUser({

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

@@ -15,6 +15,7 @@ export interface BillingInfo {
 export interface SendResult {
     success: number;
     failed: number;
+    reason?: 'no_recipients';
     billing?: BillingInfo;
 }
 export interface NotificationAction {
@@ -111,10 +112,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;
@@ -134,6 +136,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;
@@ -279,7 +298,7 @@ export interface ABTest {
     variants: any[];
     createdAt: string;
 }
-export type WebhookEvent = 'message.sent' | 'message.delivered' | 'message.opened' | 'message.clicked' | 'device.registered' | 'device.unregistered';
+export type WebhookEvent = 'message.sent' | 'message.delivered' | 'message.failed' | 'message.no_recipients' | 'message.opened' | 'message.clicked' | 'device.registered' | 'device.unregistered';
 export interface CreateWebhookOptions {
     name: string;
     url: string;

package/package.json

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