@billdog.io/notifications

Comprehensive notifications SDK for BillDog with advanced analytics, campaign management, A/B testing, and third-party integrations.

Features

Core Notifications

• ✅ Push notifications (iOS, Android, Web, Huawei)
• ✅ In-app messages
• ✅ Permission management
• ✅ Device registration
• ✅ User tagging and segmentation

Advanced Analytics & Reporting

• ✅ Comprehensive metrics (delivery, open, click, conversion rates)
• ✅ Platform-specific analytics
• ✅ Time-series data
• ✅ Time-to-conversion analysis
• ✅ Campaign performance tracking
• ✅ A/B test results with statistical significance
• ✅ Export to CSV/JSON

Campaign Management

• ✅ Create and manage campaigns
• ✅ Immediate, scheduled, and recurring campaigns
• ✅ Frequency capping
• ✅ Advanced targeting and segmentation
• ✅ Campaign pause/resume
• ✅ Campaign analytics

Segmentation & Targeting

• ✅ User segmentation with complex criteria
• ✅ Dynamic segment evaluation
• ✅ Segment testing
• ✅ Behavioral targeting
• ✅ Attribute-based targeting

Batch Operations

• ✅ Send bulk notifications efficiently
• ✅ Priority queuing (high/normal/low)
• ✅ Scheduled batch sends
• ✅ Deduplication
• ✅ Batch status tracking

Integration Layer

• ✅ OneSignal integration
• ✅ Firebase Cloud Messaging
• ✅ Airship (Urban Airship)
• ✅ Custom provider support
• ✅ Device sync from external providers

Server-authoritative audience

Campaign audience, segment membership, channel eligibility, consent, and targeting rules are resolved by BillDog server-side delivery endpoints. The Notifications SDK handles device registration, display, and lifecycle events; it does not import or evaluate @billdog.io/segments or @billdog.io/targeting at runtime.

Installation

npm install @billdog.io/notifications @billdog.io/core

Quick Start

import { notifications } from '@billdog.io/notifications';

// Configure SDK
notifications.configure({
  apiKey: 'your-api-key',
  projectUrl: 'https://your-project.supabase.co',
  enableLogging: true
});

// Request permission
const status = await notifications.requestPermission();

// Register device
await notifications.registerDevice(pushToken, 'ios');

// Set user ID
await notifications.setExternalUserId('user_123');

Advanced Usage

Analytics & Reporting

// Get comprehensive analytics
const analytics = await notifications.getAnalytics(
  new Date('2024-01-01'),
  new Date('2024-01-31'),
  {
    platform: 'ios',
    campaignId: 'campaign_123'
  }
);

console.log('Conversion rate:', analytics.conversion_rate);
console.log('Total revenue:', analytics.total_revenue);

// Get campaign stats
const campaignStats = await notifications.getCampaignStats('campaign_123');

// Get A/B test results
const abResults = await notifications.getABTestResults('test_123');
console.log('Winner:', abResults.winner);
console.log('Confidence:', abResults.confidence_level);

// Export data
const csvBlob = await notifications.exportAnalytics(
  new Date('2024-01-01'),
  new Date('2024-01-31'),
  'csv'
);

Campaign Management

// Create campaign
const campaignId = await notifications.createCampaign({
  name: 'Weekend Sale',
  content: {
    title: '50% Off This Weekend!',
    body: 'Shop now and save big',
    data: { promo_code: 'WEEKEND50' }
  },
  targeting: {
    conditions: [
      { field: 'subscription_status', operator: 'eq', value: 'active' },
      { field: 'last_purchase_days', operator: 'gte', value: 30 }
    ],
    operator: 'AND'
  },
  schedule: {
    type: 'scheduled',
    startDate: new Date('2024-02-10T09:00:00Z'),
    endDate: new Date('2024-02-12T23:59:59Z')
  },
  frequencyCap: {
    maxSends: 1,
    periodHours: 24
  }
});

// Pause campaign
await notifications.toggleCampaign(campaignId, false);

Segmentation

// Create segment
const segmentId = await notifications.createSegment({
  name: 'High-Value Churned Users',
  description: 'Users with high LTV who haven\'t purchased in 60 days',
  criteria: {
    conditions: [
      { field: 'lifetime_value', operator: 'gte', value: 1000 },
      { field: 'last_purchase_days', operator: 'gte', value: 60 }
    ],
    operator: 'AND'
  }
});

// Get users in segment
const users = await notifications.getSegmentUsers(segmentId);

Batch Operations

// Send batch notifications
const result = await notifications.sendBatch({
  notifications: [
    {
      user_id: 'user_1',
      payload: { title: 'Welcome!', body: 'Thanks for signing up' }
    },
    // ... more notifications
  ],
  priority: 'high'
});

console.log('Batch ID:', result.batch_id);

Third-Party Integrations

// Connect OneSignal
await notifications.connectProvider({
  type: 'onesignal',
  credentials: {
    app_id: 'your-onesignal-app-id',
    api_key: 'your-onesignal-api-key'
  }
});

// Sync devices
const syncResult = await notifications.syncWithProvider('onesignal');

Event Handlers

// Handle received notifications
notifications.setNotificationReceivedHandler((payload) => {
  console.log('Notification received:', payload);
});

// Handle opened notifications
notifications.setNotificationOpenedHandler((payload, actionId) => {
  console.log('Notification opened:', payload, actionId);
});

// Handle in-app message clicks
notifications.setInAppMessageClickedHandler((message, actionId) => {
  console.log('In-app message clicked:', message, actionId);
});

Edge Functions

The SDK uses the following edge functions:

• notification-analytics - Fetch comprehensive analytics
• notification-batch-send - Send bulk notifications
• notification-export - Export data to CSV/JSON
• notification-integration-sync - Sync with third-party providers
• send-push-notification - Send individual notifications
• ingest-events - Track opens / conversions / engagement analytics (canonical)
• fcm-delivery-webhook / apns-delivery-callback / email-webhook / sms-webhook - Channel-specific delivery state callbacks
• email-click-tracker - Email click attribution
• register-push-device - Register device tokens

License

MIT