Reservamos Browser Analytics

This library is a lightweight and optimized solution for tracking user events and utilizing an identification system to build user preferences, designed to be used in any Single Page Application (SPA). It allows third-party websites to send predefined events with ease.

Features

• Modular and maintainable TypeScript code
• Functional programming approach
• Strong type safety with TypeScript
• Clear and concise error handling
• Easy integration with minimal configuration
• Comprehensive documentation and usage examples

Installation

To install the library, use npm or yarn

  npm install @reservamos/browser-analytics

Usage

// Import the tracker and the InitConfig interface if you want to use type safety
import analytics, { InitConfig } from '@reservamos/browser-analytics';

// Define the configuration for the tracker
const config: InitConfig = {
  mixpanelToken: 'YOUR_MIXPANEL_TOKEN',
  identificationKey: 'YOUR_IDENTIFICATION_KEY',
  debug: true,
};

// Initialize the tracker with the config
analytics.init(config);

// Listen for the "Tracker Ready" event
window.addEventListener('Tracker Ready', () => {
  console.log('Tracker Ready');

  // Track a test event
  analytics.track.test();
});

appName is optional. When provided, it is sent as the x-app-name HTTP header on Datalake identify and anonymous-profile requests so the API can identify the originating client platform.

Identifying Users

The identify method accepts a main identifier and an object containing user information. The object has four predefined fields: email, firstName, lastName, and phone. In addition to these, you can include any custom fields to store additional user-specific information as needed.

import analytics from '@reservamos/browser-analytics';

// Identify the user with the main identifier and additional information

analytics.identify('main-identifier', {
  email: 'example',
  firstName: 'John',
  lastName: 'Doe',
  phone: '123456789',
  salesforceId: '123456789',
});

Development workflow (OpenSpec)

This repo uses OpenSpec for spec-driven development. Changes are planned as artifacts under openspec/changes/ before implementation.

Prerequisites

Install the OpenSpec CLI (v1.4.1 or later — required for --json output fields used by the agent skills):

npm install -g @fission-ai/openspec
openspec --version  # must be >= 1.4.1

Commands

Use these slash commands in Cursor or Claude Code:

| Command | Purpose | |---|---| | /opsx-explore | Explore ideas and clarify requirements (no code changes) | | /opsx-propose | Create a change with proposal, design, specs, and tasks | | /opsx-apply | Implement tasks from an active change | | /opsx-sync | Sync delta specs from a change to main specs | | /opsx-archive | Archive a completed change |

Typical flow

1. /opsx-explore — think through the problem
2. /opsx-propose my-change-name — generate planning artifacts
3. /opsx-apply — implement the tasks
4. /opsx-sync — merge specs into openspec/specs/
5. /opsx-archive — move the change to openspec/changes/archive/