@savant-realms/sentinel-analytics-realm 0.0.3

package/README.md

@@ -0,0 +1,251 @@
+# 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

package/dist/index.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Configuration options for the Sentinel Analytics Realm plugin
+ */
+export interface SentinelAnalyticsRealmConfig {
+    projectId?: string;
+    appId?: string;
+    env?: string;
+    accessToken?: string;
+    baseUrl?: string;
+}
+/**
+ * Event data structure for tracking
+ */
+export 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;
+}
+/**
+ * Response from the API
+ */
+export interface ApiResponse {
+    status?: string;
+    event_id?: string;
+    events?: Array<{
+        event_id: string;
+        status: string;
+    }>;
+}
+/**
+ * Client for plugging an app into the Sentinel Analytics Realm.
+ * Supports Option A (HTTP Ingestion) with the canonical event taxonomy.
+ *
+ * Works in both Node.js and browser environments.
+ */
+export declare class SentinelAnalyticsRealmPlugin {
+    private projectId?;
+    private appId?;
+    private env;
+    private accessToken?;
+    private baseUrl;
+    /**
+     * Creates a new instance of the Sentinel Analytics Realm plugin
+     *
+     * @param config Configuration options. Can also be read from environment variables:
+     *   - SENTINEL_ANALYTICS_REALM_PROJECT_ID
+     *   - SENTINEL_ANALYTICS_REALM_APP_ID
+     *   - SENTINEL_ANALYTICS_REALM_ENV (defaults to 'prod')
+     *   - SENTINEL_ANALYTICS_REALM_URL (defaults to 'https://api.sentinelanalyticsrealm.com')
+     */
+    constructor(config?: SentinelAnalyticsRealmConfig);
+    /**
+     * Track a single event
+     *
+     * @param name Event name (required)
+     * @param eventData Additional event data
+     * @param timeout Request timeout in milliseconds (default: 5000)
+     * @returns API response or null on error
+     */
+    track(name: string, eventData?: Omit<EventData, 'name'>, timeout?: number): Promise<ApiResponse | null>;
+    /**
+     * Track multiple events in one call
+     *
+     * @param events Array of event data objects, each must have a 'name' field
+     * @param timeout Request timeout in milliseconds (default: 10000)
+     * @returns API response or null on error
+     */
+    trackBatch(events: EventData[], timeout?: number): Promise<ApiResponse | null>;
+    /**
+     * Convenience method for identity linking
+     *
+     * @param userId User ID (required)
+     * @param visitorId Visitor ID (optional)
+     * @param traits Additional user traits/properties
+     * @returns API response or null on error
+     */
+    identify(userId: string, visitorId?: string, traits?: Record<string, any>): Promise<ApiResponse | null>;
+    /**
+     * Builds the event payload for the API
+     */
+    private buildEventPayload;
+    /**
+     * Normalizes base URL by removing trailing slashes
+     */
+    private normalizeBaseUrl;
+    /**
+     * Reads environment variable (Node.js only, returns undefined in browser)
+     */
+    private readEnv;
+}
+export default SentinelAnalyticsRealmPlugin;

package/dist/index.js

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SentinelAnalyticsRealmPlugin = void 0;
+const uuid_1 = require("uuid");
+/**
+ * Client for plugging an app into the Sentinel Analytics Realm.
+ * Supports Option A (HTTP Ingestion) with the canonical event taxonomy.
+ *
+ * Works in both Node.js and browser environments.
+ */
+class SentinelAnalyticsRealmPlugin {
+    /**
+     * Creates a new instance of the Sentinel Analytics Realm plugin
+     *
+     * @param config Configuration options. Can also be read from environment variables:
+     *   - SENTINEL_ANALYTICS_REALM_PROJECT_ID
+     *   - SENTINEL_ANALYTICS_REALM_APP_ID
+     *   - SENTINEL_ANALYTICS_REALM_ENV (defaults to 'prod')
+     *   - SENTINEL_ANALYTICS_REALM_URL (defaults to 'https://api.sentinelanalyticsrealm.com')
+     */
+    constructor(config = {}) {
+        this.projectId = config.projectId || this.readEnv('SENTINEL_ANALYTICS_REALM_PROJECT_ID');
+        this.appId = config.appId || this.readEnv('SENTINEL_ANALYTICS_REALM_APP_ID');
+        this.env = config.env || this.readEnv('SENTINEL_ANALYTICS_REALM_ENV') || 'prod';
+        this.accessToken = config.accessToken;
+        this.baseUrl = this.normalizeBaseUrl(config.baseUrl ||
+            this.readEnv('SENTINEL_ANALYTICS_REALM_URL') ||
+            'https://api.sentinelanalyticsrealm.com');
+    }
+    /**
+     * Track a single event
+     *
+     * @param name Event name (required)
+     * @param eventData Additional event data
+     * @param timeout Request timeout in milliseconds (default: 5000)
+     * @returns API response or null on error
+     */
+    async track(name, eventData = {}, timeout = 5000) {
+        const url = `${this.baseUrl}/api/v1/ingest/events`;
+        const headers = {
+            'Content-Type': 'application/json',
+        };
+        if (this.accessToken) {
+            headers['Authorization'] = `Bearer ${this.accessToken}`;
+        }
+        const payload = this.buildEventPayload({
+            name,
+            ...eventData,
+        });
+        try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), timeout);
+            const response = await fetch(url, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(payload),
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (response.ok) {
+                const text = await response.text();
+                return text ? JSON.parse(text) : {};
+            }
+            // Swallow error; return null per Python SDK behavior
+            return null;
+        }
+        catch (error) {
+            // Swallow error; return null per Python SDK behavior
+            return null;
+        }
+    }
+    /**
+     * Track multiple events in one call
+     *
+     * @param events Array of event data objects, each must have a 'name' field
+     * @param timeout Request timeout in milliseconds (default: 10000)
+     * @returns API response or null on error
+     */
+    async trackBatch(events, timeout = 10000) {
+        const url = `${this.baseUrl}/api/v1/ingest/events/batch`;
+        const headers = {
+            'Content-Type': 'application/json',
+        };
+        if (this.accessToken) {
+            headers['Authorization'] = `Bearer ${this.accessToken}`;
+        }
+        const batchPayload = {
+            project_id: this.projectId,
+            app_id: this.appId,
+            env: this.env,
+            events: events.map(event => this.buildEventPayload(event)),
+        };
+        try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), timeout);
+            const response = await fetch(url, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(batchPayload),
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (response.ok) {
+                const text = await response.text();
+                return text ? JSON.parse(text) : {};
+            }
+            return null;
+        }
+        catch (error) {
+            return null;
+        }
+    }
+    /**
+     * Convenience method for identity linking
+     *
+     * @param userId User ID (required)
+     * @param visitorId Visitor ID (optional)
+     * @param traits Additional user traits/properties
+     * @returns API response or null on error
+     */
+    async identify(userId, visitorId, traits) {
+        return this.track('identify', {
+            userId,
+            visitorId,
+            properties: traits,
+        });
+    }
+    /**
+     * Builds the event payload for the API
+     */
+    buildEventPayload(eventData) {
+        const now = new Date().toISOString();
+        const eventId = (0, uuid_1.v4)();
+        return {
+            project_id: this.projectId,
+            app_id: this.appId,
+            env: this.env,
+            event_id: eventId,
+            occurred_at: now,
+            sent_at: now,
+            origin: eventData.origin || 'real',
+            identity: {
+                visitor_id: eventData.visitorId || null,
+                user_id: eventData.userId || null,
+                session_id: eventData.sessionId || null,
+            },
+            event: {
+                name: eventData.name,
+                category: eventData.category || null,
+                action: eventData.action || null,
+                label: eventData.label || null,
+                value: eventData.value || null,
+            },
+            context: eventData.context || {},
+            properties: eventData.properties || {},
+        };
+    }
+    /**
+     * Normalizes base URL by removing trailing slashes
+     */
+    normalizeBaseUrl(url) {
+        return url.endsWith('/') ? url.slice(0, -1) : url;
+    }
+    /**
+     * Reads environment variable (Node.js only, returns undefined in browser)
+     */
+    readEnv(key) {
+        // In browser environment, process.env is not available
+        if (typeof process !== 'undefined' && process.env) {
+            return process.env[key];
+        }
+        return undefined;
+    }
+}
+exports.SentinelAnalyticsRealmPlugin = SentinelAnalyticsRealmPlugin;
+// Default export
+exports.default = SentinelAnalyticsRealmPlugin;

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@savant-realms/sentinel-analytics-realm",
+  "version": "0.0.3",
+  "description": "TypeScript/JavaScript SDK for Sentinel Analytics Realm",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "lint": "eslint src --ext .ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "analytics",
+    "tracking",
+    "sentinel",
+    "savant-realms"
+  ],
+  "author": "Savant Realms",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/savant-realms/sentinel-analytics-realm-ts-js.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.0.0",
+    "@types/uuid": "^9.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "eslint": "^8.0.0",
+    "jest": "^29.5.0",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "uuid": "^9.0.0"
+  },
+  "peerDependencies": {},
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}