Sentinel Analytics Realm - TypeScript/JavaScript SDK

TypeScript/JavaScript SDK for the Sentinel Analytics Realm analytics platform. Works in both Node.js and browser environments.

Installation

npm install @savant-realms/sentinel-analytics-realm

or

yarn add @savant-realms/sentinel-analytics-realm

Usage

Basic Setup

import { SentinelAnalyticsRealmPlugin } from '@savant-realms/sentinel-analytics-realm';

const analytics = new SentinelAnalyticsRealmPlugin({
  projectId: 'your-project-id',
  appId: 'your-app-id',
  env: 'prod', // or 'dev', 'staging'
  accessToken: 'your-access-token', // optional
  baseUrl: 'https://api.sentinelanalyticsrealm.com', // optional, defaults to this
});

Environment Variables (Node.js only)

You can also configure the SDK using environment variables:

export SENTINEL_ANALYTICS_REALM_PROJECT_ID="your-project-id"
export SENTINEL_ANALYTICS_REALM_APP_ID="your-app-id"
export SENTINEL_ANALYTICS_REALM_ENV="prod"
export SENTINEL_ANALYTICS_REALM_URL="https://api.sentinelanalyticsrealm.com"

Then initialize without parameters:

const analytics = new SentinelAnalyticsRealmPlugin();

Tracking Events

Single Event

await analytics.track('page_view', {
  visitorId: 'visitor-123',
  userId: 'user-456',
  sessionId: 'session-789',
  category: 'navigation',
  action: 'view',
  label: 'Home Page',
  properties: {
    path: '/home',
    referrer: 'https://example.com',
  },
  context: {
    userAgent: navigator.userAgent,
    screenWidth: window.screen.width,
  },
});

Batch Events

await analytics.trackBatch([
  {
    name: 'page_view',
    visitorId: 'visitor-123',
    properties: { path: '/home' },
  },
  {
    name: 'button_click',
    visitorId: 'visitor-123',
    properties: { button: 'signup' },
  },
]);

Identity Linking

await analytics.identify('user-456', 'visitor-123', {
  email: '[email protected]',
  name: 'John Doe',
  plan: 'premium',
});

JavaScript (CommonJS)

const { SentinelAnalyticsRealmPlugin } = require('@savant-realms/sentinel-analytics-realm');

const analytics = new SentinelAnalyticsRealmPlugin({
  projectId: 'your-project-id',
  appId: 'your-app-id',
});

analytics.track('page_view', {
  visitorId: 'visitor-123',
});

Browser Usage

For browser usage, you'll need a bundler like Webpack, Vite, or Rollup that supports CommonJS modules, or use a CDN that provides ES modules.

Alternatively, you can use a bundler to create a browser-compatible build:

// In your bundler configuration, ensure the SDK is included
import { SentinelAnalyticsRealmPlugin } from '@savant-realms/sentinel-analytics-realm';

API Reference

SentinelAnalyticsRealmPlugin

Main class for interacting with the Sentinel Analytics Realm API.

Constructor

new SentinelAnalyticsRealmPlugin(config?: SentinelAnalyticsRealmConfig)

Config Options:

• projectId?: string - Your project ID
• appId?: string - Your application ID
• env?: string - Environment ('prod', 'dev', 'staging'), defaults to 'prod'
• accessToken?: string - Optional access token for authentication
• baseUrl?: string - API base URL, defaults to 'https://api.sentinelanalyticsrealm.com'

Methods

track(name, eventData?, timeout?)

Track a single event.

• name: string - Event name (required)
• eventData?: EventData - Event data object
• timeout?: number - Request timeout in milliseconds (default: 5000)
• Returns: Promise<ApiResponse | null>

trackBatch(events, timeout?)

Track multiple events in one call.

• events: EventData[] - Array of event data objects
• timeout?: number - Request timeout in milliseconds (default: 10000)
• Returns: Promise<ApiResponse | null>

identify(userId, visitorId?, traits?)

Convenience method for identity linking.

• userId: string - User ID (required)
• visitorId?: string - Visitor ID (optional)
• traits?: Record<string, any> - User traits/properties
• Returns: Promise<ApiResponse | null>

EventData Interface

interface EventData {
  name: string;
  visitorId?: string;
  userId?: string;
  sessionId?: string;
  category?: string;
  action?: string;
  label?: string;
  value?: number;
  properties?: Record<string, any>;
  context?: Record<string, any>;
  origin?: string; // 'real' or 'seed', defaults to 'real'
}

Error Handling

The SDK follows a fail-silent approach similar to the Python SDK. If an error occurs during tracking, the methods return null instead of throwing an exception. This ensures your application continues to function even if analytics tracking fails.

TypeScript Support

This package includes full TypeScript type definitions. No additional @types package is required.

Development

Building

npm install
npm run build

Testing

npm test

Deployment

To publish the package to npm, use the deployment script:

# Set your npm token (or add to .env file)
export NPM_TOKEN=your_npm_token_here

# Run deployment (builds, tests, and publishes)
./scripts/deploy.sh

# Or run in dry-run mode (builds and validates, but doesn't publish)
DRY_RUN=true ./scripts/deploy.sh

The deployment script will:

1. Install dependencies
2. Build the TypeScript package
3. Run tests (if configured)
4. Validate package.json
5. Publish to npm (if NPM_TOKEN is set)
6. Optionally publish to GitLab Package Registry (if GITLAB_NPM_TOKEN and CI_PROJECT_URL are set)

You can also publish manually:

npm run build
npm publish

License

MIT

Author

Savant Realms