@rivium/push-node 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Rivium
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,369 @@
+# RiviumPush Node.js SDK
+
+Server-side SDK for [RiviumPush](https://rivium.co) — push notifications, inbox, in-app messages, and more.
+
+## Installation
+
+```bash
+npm install @rivium-push/node
+```
+
+## Quick Start
+
+```typescript
+import { RiviumPush } from '@rivium-push/node';
+
+const riviumPush = new RiviumPush({
+  apiKey: 'rv_live_xxxxxxxxxxxxxxxxxxxxx',
+  serverSecret: 'rv_srv_xxxxxxxxxxxxxxxxxxxxx', // Required for server-side operations
+});
+
+// Send a push notification
+await riviumPush.push.sendToUser({
+  userId: 'user-123',
+  title: 'Order Shipped',
+  body: 'Your order #1234 has been shipped!',
+  data: { orderId: '1234' },
+});
+```
+
+> **Note:** Both `apiKey` and `serverSecret` are required for all server-side SDK operations. You can find these credentials in your [Rivium Console](https://console.rivium.co) when you create a project.
+
+## Push Notifications
+
+```typescript
+// Send to a specific device
+await riviumPush.push.sendToDevice({
+  deviceId: 'device-uuid',
+  title: 'Hello',
+  body: 'Welcome to our app!',
+});
+
+// Send to a user (all their devices)
+await riviumPush.push.sendToUser({
+  userId: 'user-123',
+  title: 'New Message',
+  body: 'You have a new message',
+});
+
+// Send to multiple devices
+await riviumPush.push.sendToDevices({
+  deviceIds: ['device-1', 'device-2', 'device-3'],
+  title: 'Update Available',
+  body: 'A new version is available',
+});
+
+// Send to a topic (e.g., "promotions")
+await riviumPush.push.sendToTopic({
+  topic: 'promotions',
+  title: 'Flash Sale!',
+  body: '50% off everything today only',
+  imageUrl: 'https://example.com/sale.jpg',
+});
+
+// Send to a segment
+await riviumPush.push.sendToSegment({
+  segmentId: 'segment-uuid',
+  title: 'Exclusive Offer',
+  body: 'Just for our VIP customers',
+});
+
+// Broadcast to all devices
+await riviumPush.push.broadcast({
+  title: 'App Update',
+  body: 'Check out the new features!',
+});
+```
+
+### Rich Notifications
+
+```typescript
+await riviumPush.push.sendToUser({
+  userId: 'user-123',
+  title: 'New Product',
+  body: 'Check out our latest arrival',
+  imageUrl: 'https://example.com/product.jpg',
+  actions: [
+    { id: 'buy', title: 'Buy Now', action: 'OPEN_PRODUCT' },
+    { id: 'later', title: 'Save for Later' },
+  ],
+  deepLink: 'myapp://product/123',
+  data: { productId: '123' },
+});
+```
+
+### Using Templates
+
+```typescript
+await riviumPush.push.sendToUser({
+  userId: 'user-123',
+  templateId: 'order-shipped-template',
+  templateVariables: {
+    orderNumber: '#1234',
+    trackingUrl: 'https://track.example.com/1234',
+  },
+});
+```
+
+## Inbox Messages
+
+```typescript
+// Send inbox message to a user
+await riviumPush.inbox.sendToUser({
+  userId: 'user-123',
+  content: {
+    title: 'Welcome!',
+    body: 'Thanks for joining us.',
+    imageUrl: 'https://example.com/welcome.jpg',
+    deepLink: 'myapp://onboarding',
+  },
+});
+
+// Send to multiple users
+await riviumPush.inbox.sendToUsers({
+  userIds: ['user-1', 'user-2', 'user-3'],
+  content: {
+    title: 'New Feature',
+    body: 'Check out our latest feature',
+  },
+});
+
+// Broadcast to all
+await riviumPush.inbox.broadcast({
+  content: {
+    title: 'Holiday Sale',
+    body: 'Up to 70% off!',
+  },
+  expiresAt: '2025-12-31T23:59:59Z',
+});
+```
+
+## Device Management
+
+```typescript
+// List all devices
+const devices = await riviumPush.devices.list();
+
+// Subscribe a device to a topic
+await riviumPush.devices.subscribeTopic('device-uuid', 'news');
+
+// Unsubscribe from a topic
+await riviumPush.devices.unsubscribeTopic('device-uuid', 'news');
+
+// Associate device with a user
+await riviumPush.devices.setUserId('device-uuid', 'user-123');
+
+// Delete a device
+await riviumPush.devices.delete('device-uuid');
+```
+
+## Templates
+
+```typescript
+// Create a template
+const template = await riviumPush.templates.create({
+  name: 'Order Shipped',
+  title: 'Your order {{orderNumber}} has shipped!',
+  body: 'Track your package: {{trackingUrl}}',
+  variables: ['orderNumber', 'trackingUrl'],
+});
+
+// List templates
+const templates = await riviumPush.templates.list();
+
+// Render a template (preview)
+const rendered = await riviumPush.templates.render(template.id, {
+  orderNumber: '#1234',
+  trackingUrl: 'https://track.example.com/1234',
+});
+```
+
+## Segments
+
+```typescript
+// Create a segment
+const segment = await riviumPush.segments.create({
+  name: 'VIP Customers',
+  description: 'Customers with more than 10 orders',
+  filters: [
+    { field: 'metadata.orders', operator: 'gt', value: 10 },
+  ],
+});
+
+// Get devices in a segment
+const devices = await riviumPush.segments.getDevices(segment.id);
+
+// Recalculate segment membership
+await riviumPush.segments.recalculate(segment.id);
+```
+
+## Scheduled Messages
+
+```typescript
+// Schedule a message
+const scheduled = await riviumPush.scheduled.create({
+  title: 'Reminder',
+  body: 'Don\'t forget to complete your purchase!',
+  targetType: 'user',
+  targetValue: 'user-123',
+  scheduledAt: '2025-02-14T09:00:00Z',
+  timezone: 'America/New_York',
+});
+
+// List pending messages
+const pending = await riviumPush.scheduled.listPending();
+
+// Cancel a scheduled message
+await riviumPush.scheduled.cancel(scheduled.id);
+```
+
+## Webhooks
+
+```typescript
+// Create a webhook
+const webhook = await riviumPush.webhooks.create({
+  name: 'Order Events',
+  url: 'https://example.com/webhooks/rivium-push',
+  events: ['message.delivered', 'message.opened', 'message.clicked'],
+  secret: 'my-secret-key',
+});
+
+// Test a webhook
+await riviumPush.webhooks.test(webhook.id, 'message.opened');
+
+// Get delivery logs
+const logs = await riviumPush.webhooks.getLogs(webhook.id);
+```
+
+## Analytics
+
+```typescript
+// Get overview stats
+const overview = await riviumPush.analytics.getOverview();
+console.log(`Delivery rate: ${overview.deliveryRate}%`);
+
+// Get daily stats
+const daily = await riviumPush.analytics.getDaily(30); // Last 30 days
+
+// Get app stats
+const stats = await riviumPush.analytics.getStats();
+console.log(`Total devices: ${stats.totalDevices}`);
+```
+
+## A/B Testing
+
+```typescript
+// Create an A/B test
+const test = await riviumPush.abTesting.create({
+  appId: 'your-app-id',
+  name: 'Notification Copy Test',
+  variants: [
+    {
+      name: 'Control',
+      title: 'Check this out',
+      body: 'See what\'s new',
+      trafficPercentage: 50,
+    },
+    {
+      name: 'Urgency',
+      title: 'Don\'t miss out!',
+      body: 'Limited time offer',
+      trafficPercentage: 50,
+    },
+  ],
+});
+
+// Start the test
+await riviumPush.abTesting.start(test.id);
+
+// Get results
+const results = await riviumPush.abTesting.getResults(test.id);
+```
+
+## In-App Messages
+
+```typescript
+// Create an in-app message
+const message = await riviumPush.inApp.create('your-app-id', {
+  name: 'Welcome Modal',
+  type: 'modal',
+  content: {
+    title: 'Welcome!',
+    body: 'Thanks for downloading our app',
+    imageUrl: 'https://example.com/welcome.jpg',
+    buttons: [
+      { id: 'start', text: 'Get Started', action: 'dismiss', style: 'primary' },
+    ],
+  },
+  triggerType: 'on_app_open',
+  maxImpressions: 1,
+});
+
+// Activate the message
+await riviumPush.inApp.activate('your-app-id', message.id);
+```
+
+## Error Handling
+
+```typescript
+import { RiviumPush, RiviumPushError } from '@rivium-push/node';
+
+try {
+  await riviumPush.push.sendToUser({
+    userId: 'user-123',
+    title: 'Hello',
+    body: 'World',
+  });
+} catch (error) {
+  if (error instanceof RiviumPushError) {
+    console.error(`Status: ${error.statusCode}`);
+    console.error(`Message: ${error.message}`);
+    console.error(`Response:`, error.response);
+  }
+}
+```
+
+## Configuration
+
+```typescript
+const riviumPush = new RiviumPush({
+  apiKey: 'rv_live_xxxxxxxxxxxxxxxxxxxxx',        // Required - from Rivium Console
+  serverSecret: 'rv_srv_xxxxxxxxxxxxxxxxxxxxx',   // Required - from Rivium Console
+});
+```
+
+### Environment Variables
+
+We recommend using environment variables to store your credentials:
+
+```typescript
+const riviumPush = new RiviumPush({
+  apiKey: process.env.RIVIUM_API_KEY!,
+  serverSecret: process.env.RIVIUM_SERVER_SECRET!,
+});
+```
+
+```bash
+# .env
+RIVIUM_API_KEY=rv_live_xxxxxxxxxxxxxxxxxxxxx
+RIVIUM_SERVER_SECRET=rv_srv_xxxxxxxxxxxxxxxxxxxxx
+```
+
+### Credentials
+
+| Credential | Format | Description |
+|------------|--------|-------------|
+| **API Key** | `rv_live_xxx` | Used for client-side SDKs (iOS, Android, Web) and server-side SDKs |
+| **Server Secret** | `rv_srv_xxx` | **Required** for server-side operations. Never expose in client-side code. |
+
+Both credentials are generated when you create a project in the [Rivium Console](https://console.rivium.co). Store them securely and never commit them to version control.
+
+## Links
+
+- [Rivium Push](https://rivium.co/cloud/rivium-push) - Learn more about Rivium Push
+- [Documentation](https://rivium.co/cloud/rivium-push/docs/quick-start) - Full documentation and guides
+- [Rivium Console](https://console.rivium.co) - Manage your push notifications
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

package/dist/client.d.ts

@@ -0,0 +1,18 @@
+import { RiviumPushConfig } from './types';
+export declare class HttpClient {
+    private apiKey;
+    private serverSecret;
+    private baseUrl;
+    constructor(config: RiviumPushConfig);
+    request<T>(method: string, path: string, body?: any, query?: Record<string, any>): Promise<T>;
+    get<T>(path: string, query?: Record<string, any>): Promise<T>;
+    post<T>(path: string, body?: any, query?: Record<string, any>): Promise<T>;
+    put<T>(path: string, body?: any, query?: Record<string, any>): Promise<T>;
+    patch<T>(path: string, body?: any): Promise<T>;
+    delete<T>(path: string, body?: any, query?: Record<string, any>): Promise<T>;
+}
+export declare class RiviumPushError extends Error {
+    statusCode: number;
+    response: any;
+    constructor(message: string, statusCode: number, response: any);
+}

package/dist/client.js

@@ -0,0 +1,99 @@
+"use strict";
+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;
+const https_1 = __importDefault(require("https"));
+const http_1 = __importDefault(require("http"));
+const BASE_URL = 'https://push-api.rivium.co';
+class HttpClient {
+    constructor(config) {
+        if (!config.apiKey) {
+            throw new Error('RiviumPush: apiKey is required');
+        }
+        if (!config.serverSecret) {
+            throw new Error('RiviumPush: serverSecret is required for server-side operations');
+        }
+        this.apiKey = config.apiKey;
+        this.serverSecret = config.serverSecret;
+        this.baseUrl = BASE_URL;
+    }
+    async request(method, path, body, query) {
+        const url = new URL(path, this.baseUrl);
+        if (query) {
+            for (const [k, v] of Object.entries(query)) {
+                if (v !== undefined && v !== null) {
+                    url.searchParams.set(k, String(v));
+                }
+            }
+        }
+        const payload = body ? JSON.stringify(body) : undefined;
+        const isHttps = url.protocol === 'https:';
+        const lib = isHttps ? https_1.default : http_1.default;
+        // Build headers
+        const headers = {
+            'x-api-key': this.apiKey,
+            'x-server-secret': this.serverSecret,
+            'Content-Type': 'application/json',
+        };
+        if (payload) {
+            headers['Content-Length'] = Buffer.byteLength(payload);
+        }
+        return new Promise((resolve, reject) => {
+            const req = lib.request(url, {
+                method,
+                headers,
+            }, (res) => {
+                let data = '';
+                res.on('data', (chunk) => (data += chunk));
+                res.on('end', () => {
+                    const statusCode = res.statusCode || 0;
+                    let parsed;
+                    try {
+                        parsed = data ? JSON.parse(data) : {};
+                    }
+                    catch {
+                        parsed = { message: data };
+                    }
+                    if (statusCode >= 200 && statusCode < 300) {
+                        resolve(parsed);
+                    }
+                    else {
+                        const err = new RiviumPushError(parsed.message || `Request failed with status ${statusCode}`, statusCode, parsed);
+                        reject(err);
+                    }
+                });
+            });
+            req.on('error', reject);
+            if (payload)
+                req.write(payload);
+            req.end();
+        });
+    }
+    get(path, query) {
+        return this.request('GET', path, undefined, query);
+    }
+    post(path, body, query) {
+        return this.request('POST', path, body, query);
+    }
+    put(path, body, query) {
+        return this.request('PUT', path, body, query);
+    }
+    patch(path, body) {
+        return this.request('PATCH', path, body);
+    }
+    delete(path, body, query) {
+        return this.request('DELETE', path, body, query);
+    }
+}
+exports.HttpClient = HttpClient;
+class RiviumPushError extends Error {
+    constructor(message, statusCode, response) {
+        super(message);
+        this.name = 'RiviumPushError';
+        this.statusCode = statusCode;
+        this.response = response;
+    }
+}
+exports.RiviumPushError = RiviumPushError;

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+import { Push } from './modules/push';
+import { Devices } from './modules/devices';
+import { Templates } from './modules/templates';
+import { Segments } from './modules/segments';
+import { Scheduled } from './modules/scheduled';
+import { Inbox } from './modules/inbox';
+import { InApp } from './modules/in-app';
+import { ABTesting } from './modules/ab-testing';
+import { Webhooks } from './modules/webhooks';
+import { Analytics } from './modules/analytics';
+import { RiviumPushConfig } from './types';
+export declare class RiviumPush {
+    private client;
+    /** Push notifications */
+    push: Push;
+    /** Device management */
+    devices: Devices;
+    /** Notification templates */
+    templates: Templates;
+    /** User segments */
+    segments: Segments;
+    /** Scheduled messages */
+    scheduled: Scheduled;
+    /** Inbox messages */
+    inbox: Inbox;
+    /** In-app messages */
+    inApp: InApp;
+    /** A/B testing */
+    abTesting: ABTesting;
+    /** Webhooks */
+    webhooks: Webhooks;
+    /** Analytics */
+    analytics: Analytics;
+    constructor(config: RiviumPushConfig);
+}
+export { RiviumPushError } from './client';
+export * from './types';

package/dist/index.js

@@ -0,0 +1,48 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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;
+const client_1 = require("./client");
+const push_1 = require("./modules/push");
+const devices_1 = require("./modules/devices");
+const templates_1 = require("./modules/templates");
+const segments_1 = require("./modules/segments");
+const scheduled_1 = require("./modules/scheduled");
+const inbox_1 = require("./modules/inbox");
+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");
+class RiviumPush {
+    constructor(config) {
+        this.client = new client_1.HttpClient(config);
+        this.push = new push_1.Push(this.client);
+        this.devices = new devices_1.Devices(this.client);
+        this.templates = new templates_1.Templates(this.client);
+        this.segments = new segments_1.Segments(this.client);
+        this.scheduled = new scheduled_1.Scheduled(this.client);
+        this.inbox = new inbox_1.Inbox(this.client);
+        this.inApp = new in_app_1.InApp(this.client);
+        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);
+    }
+}
+exports.RiviumPush = RiviumPush;
+var client_2 = require("./client");
+Object.defineProperty(exports, "RiviumPushError", { enumerable: true, get: function () { return client_2.RiviumPushError; } });
+// Re-export types
+__exportStar(require("./types"), exports);

package/dist/modules/ab-testing.d.ts

@@ -0,0 +1,59 @@
+import { HttpClient } from '../client';
+import { ABTest, CreateABTestOptions } from '../types';
+export declare class ABTesting {
+    private client;
+    constructor(client: HttpClient);
+    /**
+     * Create a new A/B test.
+     */
+    create(options: CreateABTestOptions & {
+        appId: string;
+    }): Promise<ABTest>;
+    /**
+     * List all A/B tests for an app.
+     */
+    list(appId: string): Promise<ABTest[]>;
+    /**
+     * Get an A/B test by ID.
+     */
+    get(id: string): Promise<ABTest>;
+    /**
+     * Get results for an A/B test.
+     */
+    getResults(id: string): Promise<any>;
+    /**
+     * Start an A/B test.
+     */
+    start(id: string): Promise<ABTest>;
+    /**
+     * Pause an A/B test.
+     */
+    pause(id: string): Promise<ABTest>;
+    /**
+     * Complete an A/B test.
+     */
+    complete(id: string, winnerId?: string): Promise<ABTest>;
+    /**
+     * Delete an A/B test.
+     */
+    delete(id: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Send an A/B test to targeted devices.
+     */
+    send(id: string): Promise<{
+        sent: number;
+    }>;
+    /**
+     * Calculate audience size for targeting options.
+     */
+    getAudienceSize(options: {
+        appId: string;
+        targetType?: string;
+        segmentId?: string;
+        targetPercentage?: number;
+    }): Promise<{
+        count: number;
+    }>;
+}