@mira-network/mira-data-stream/README.md

JavaScript SDK for Mira Data Stream analytics and event tracking

# Mira Data Stream JavaScript SDK

A lightweight, flexible SDK for tracking events, page views, and user identities in web applications.

## Installation

```bash
npm install mira-data-stream
```

## Usage

### Basic Usage

```javascript
import { track, identify, page, setWriteKey } from 'mira-data-stream';

// Set your authentication write key (required)
// You can get this from the Mira Data Stream Producer API when creating a service
setWriteKey('your-write-key-here');

// Track an event
track('button_clicked', { 
  button_id: 'signup',
  page: 'landing' 
});

// Identify a user
identify('user123', {
  name: 'John Doe',
  email: 'john@example.com'
});

// Track page view
page('home');
```

### Advanced Usage

You can create a custom instance with specific configuration:

```javascript
import { init } from 'mira-data-stream';

const analytics = init({
  apiUrl: 'https://api.example.com/tracking',
  writeKey: 'your-write-key-here', // Required for authentication
  flushInterval: 5000 // 5 seconds
});

// Use the custom instance
analytics.track('custom_event', {
  property1: 'value1',
  property2: 'value2'
});
```

### Usage in React

```jsx
import { useEffect } from 'react';
import { page, track, setWriteKey } from 'mira-data-stream';

function MyComponent() {
  useEffect(() => {
    // Set write key for authentication
    setWriteKey('your-write-key-here');
    
    // Track page view when component mounts
    page('my-component');
  }, []);

  const handleClick = () => {
    track('button_clicked', {
      component: 'MyComponent'
    });
  };

  return (
    <div>
      <h1>My Component</h1>
      <button onClick={handleClick}>Click Me</button>
    </div>
  );
}
```

## API Reference

### Functions

- `track(eventName, properties, options)` - Track an event
- `identify(userId, traits)` - Identify a user
- `page(name, properties, options)` - Track a page view
- `setWriteKey(writeKey)` - Set the write key for authentication with the server
- `flush()` - Manually flush the event queue
- `reset()` - Reset user identity
- `init(options)` - Initialize a new SDK instance with custom options

### Options

- `apiUrl` - API URL for the Mira Data Stream Backend (default: 'http://localhost:8000/api/v1')
- `userId` - User ID for identifying the current user
- `anonymousId` - Anonymous ID for tracking non-logged-in users (auto-generated if not provided)
- `writeKey` - Write key for authentication with the server (required)
- `flushInterval` - Interval in milliseconds for flushing the event queue (default: 10000)

## Authentication

The Mira Data Stream requires a write key for authentication. Each write key corresponds to a specific service in the backend.

To get a write key:
1. Create a service through the Mira Data Stream Producer API
2. Use the write key provided by the API in your SDK initialization

```javascript
// Set the write key for authentication
setWriteKey('your-write-key-here');

// Or when initializing a new instance
const analytics = init({
  writeKey: 'your-write-key-here'
});
```

## Browser Support

The SDK works in all modern browsers that support the Fetch API (Chrome, Firefox, Safari, Edge). For older browsers, you may need to include a polyfill for the Fetch API.

## Development

If you want to contribute to this SDK, see the [PUBLISHING.md](PUBLISHING.md) file for development setup, testing, and publication instructions.

```bash
# Install dependencies
npm install

# Run tests
npm test

# Build the SDK
npm run build
```

## License

MIT