npm package: @savant-realms/sentinel-analytics-realm
Description: TypeScript/JavaScript SDK for Sentinel Analytics Realm
Author: Savant Realms
Latest version: 0.0.3

# 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

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

or

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

## Usage

### Basic Setup

```typescript
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:

```bash
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:

```typescript
const analytics = new SentinelAnalyticsRealmPlugin();
```

### Tracking Events

#### Single Event

```typescript
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

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

### Identity Linking

```typescript
await analytics.identify('user-456', 'visitor-123', {
  email: 'user@example.com',
  name: 'John Doe',
  plan: 'premium',
});
```

### JavaScript (CommonJS)

```javascript
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:

```typescript
// 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

```typescript
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

```typescript
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

```bash
npm install
npm run build
```

### Testing

```bash
npm test
```

### Deployment

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

```bash
# 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:

```bash
npm run build
npm publish
```

## License

MIT

## Author

Savant Realms