@eventra_dev/eventra-sdk 0.1.2 → 0.1.4

package/README.md

@@ -1,194 +1,350 @@
 # Eventra SDK
 
-![npm](https://img.shields.io/npm/v/@eventra/sdk)
-![bundle size](https://img.shields.io/bundlephobia/minzip/@eventra/sdk)
-![license](https://img.shields.io/npm/l/@eventra/sdk)
-![types](https://img.shields.io/npm/types/@eventra/sdk)
+[![npm version](https://img.shields.io/npm/v/@eventra_dev/eventra-sdk.svg)](https://www.npmjs.com/package/@eventra_dev/eventra-sdk)
+[![npm downloads](https://img.shields.io/npm/dm/@eventra_dev/eventra-sdk.svg)](https://www.npmjs.com/package/@eventra_dev/eventra-sdk)
+[![TypeScript](https://img.shields.io/badge/typescript-ready-blue.svg)](https://www.typescriptlang.org/)
 
-Production-grade TypeScript SDK for tracking product events across **browser, server, and edge runtimes**.
+Eventra SDK allows you to send **feature usage and product analytics events** to the Eventra platform.
 
-Eventra is designed for **deterministic ingestion**, batching efficiency, and near-zero runtime overhead.
+It is designed to be:
+
+* lightweight
+* runtime-agnostic
+* resilient (batching + retry)
+* production-safe
+* TypeScript-first
 
 ---
 
-##  Features
+# Installation
 
-- UUID v4 idempotency keys
-- Safe retry policy
-- Exponential backoff with jitter
-- sendBeacon support for browsers
-- Multi-runtime support (Browser / Node / Bun / Deno / Edge)
-- Optional multi-tab leader mode
-- Queue overflow protection
-- Zero dependencies
+Install the SDK using your preferred package manager.
 
----
+### npm
+
+```bash
+npm i @eventra_dev/eventra-sdk
+```
 
-## Install
+### pnpm
 
 ```bash
-pnpm add @eventra/sdk
+pnpm add @eventra_dev/eventra-sdk
 ```
 
-or
+### yarn
 
 ```bash
-npm install @eventra/sdk
+yarn add @eventra_dev/eventra-sdk
 ```
 
 ---
 
-#  Quick Start
-
-## Browser
+# Quick Start
 
 ```ts
-import { Eventra } from "@eventra/sdk";
+import { Eventra } from "@eventra_dev/eventra-sdk";
 
 const tracker = new Eventra({
-  apiKey: "YOUR_API_KEY"
+  apiKey: "YOUR_PROJECT_API_KEY",
 });
 
 tracker.track("checkout.completed", {
-  userId: "user_123"
+  userId: "user_123",
 });
 ```
 
 ---
 
-## Node / NestJS
+# Where You Can Use Eventra SDK
+
+Eventra SDK works in many environments:
+
+* Browser applications
+* React apps
+* Next.js apps
+* Node.js backends
+* NestJS services
+* Express APIs
+* Vanilla JavaScript
+* Edge runtimes
+* Bun
+* Deno
+
+---
+
+# Browser Usage
 
 ```ts
-import { Eventra } from "@eventra/sdk";
+import { Eventra } from "@eventra_dev/eventra-sdk";
 
 const tracker = new Eventra({
-  apiKey: process.env.EVENTRA_API_KEY!
+  apiKey: "YOUR_PROJECT_API_KEY",
 });
 
-tracker.track("invoice.created", {
-  userId: "user_123"
+tracker.track("page.viewed", {
+  properties: {
+    path: window.location.pathname
+  }
 });
 ```
 
----
+The SDK automatically:
 
-#  Configuration
+* batches events
+* retries failed requests
+* flushes on page exit
 
-| Option | Default |
-|------|------|
-| flushInterval | 2000 ms |
-| maxBatchSize | 50 |
-| maxRetries | 3 |
-| maxQueueSize | 10000 |
-| retryBaseDelayMs | 300 |
+---
 
-Example:
+# React Usage
 
 ```ts
+import { useEffect } from "react";
+import { Eventra } from "@eventra_dev/eventra-sdk";
+
 const tracker = new Eventra({
-  apiKey: "API_KEY",
-  flushInterval: 2000,
-  maxBatchSize: 50
+  apiKey: "YOUR_PROJECT_API_KEY",
 });
+
+export function App() {
+
+  useEffect(() => {
+    tracker.track("app.loaded");
+  }, []);
+
+  return <div>Hello</div>;
+}
 ```
 
 ---
 
-# Reliability Model
+# Next.js Usage
+
+Client component example:
 
-### Idempotency
+```ts
+"use client";
 
-Each event receives a **UUID v4 idempotency key**, ensuring:
+import { Eventra } from "@eventra_dev/eventra-sdk";
 
-- safe retries
-- duplicate suppression
-- multi-tab safety
+const tracker = new Eventra({
+  apiKey: "YOUR_PROJECT_API_KEY",
+});
+
+export function CheckoutButton() {
+  return (
+    <button
+      onClick={() => tracker.track("checkout.started")}
+    >
+      Checkout
+    </button>
+  );
+}
+```
 
 ---
 
-### Retry Policy
+# Node.js Usage
+
+```ts
+import { Eventra } from "@eventra_dev/eventra-sdk";
 
-The SDK retries only when safe:
+const tracker = new Eventra({
+  apiKey: "YOUR_PROJECT_API_KEY",
+});
 
-✔ network failures  
-✔ HTTP 5xx
+tracker.track("invoice.created", {
+  userId: "user_123",
+});
+```
+
+---
 
-It does **not retry**:
+# NestJS Usage
 
-✖ HTTP 4xx  
-✖ validation errors  
-✖ authentication errors
+```ts
+import { Injectable } from "@nestjs/common";
+import { Eventra } from "@eventra_dev/eventra-sdk";
+
+@Injectable()
+export class BillingService {
+
+  private tracker = new Eventra({
+    apiKey: "YOUR_PROJECT_API_KEY",
+  });
+
+  charge(userId: string) {
+    this.tracker.track("invoice.created", {
+      userId
+    });
+  }
+}
+```
 
 ---
 
-### Backoff Strategy
+# Express Usage
+
+```ts
+import express from "express";
+import { Eventra } from "@eventra_dev/eventra-sdk";
+
+const app = express();
 
+const tracker = new Eventra({
+  apiKey: "YOUR_PROJECT_API_KEY",
+});
+
+app.post("/checkout", (req, res) => {
+
+  tracker.track("checkout.completed");
+
+  res.sendStatus(200);
+});
 ```
-delay = base * 2^attempt * jitter(0.5–1.5) 
+
+---
+
+# Vanilla JavaScript (CDN)
+
+You can use Eventra without a bundler.
+
+```html
+<script type="module">
+
+import { Eventra } from "https://esm.sh/@eventra_dev/eventra-sdk";
+
+const tracker = new Eventra({
+  apiKey: "YOUR_PROJECT_API_KEY",
+});
+
+tracker.track("page.viewed");
+
+</script>
 ```
 
 ---
 
-# Multi-Tab Mode
+# Configuration
 
-Default:
+You can configure the SDK behaviour.
 
 ```ts
-multiTabMode: "independent"
+const eventra = new Eventra({
+
+  apiKey: "YOUR_PROJECT_API_KEY",
+
+  endpoint: "https://api.eventra.dev/api/v1/events",
+
+  flushInterval: 2000,
+  maxBatchSize: 50,
+  maxQueueSize: 10000,
+  maxRetries: 3
+
+});
 ```
 
-Leader mode:
+---
+
+# Options
+
+| option        | description                        |
+| ------------- | ---------------------------------- |
+| apiKey        | Project API key                    |
+| endpoint      | Event ingestion endpoint           |
+| flushInterval | Batch flush interval (ms)          |
+| maxBatchSize  | Maximum events per batch           |
+| maxQueueSize  | Maximum buffered events            |
+| maxRetries    | Retry attempts for failed requests |
+| multiTabMode  | Browser tab coordination mode      |
+
+---
+
+# Multi-Tab Mode (Browser)
+
+To avoid duplicate event sending across multiple tabs:
 
 ```ts
 const tracker = new Eventra({
-  apiKey: "API_KEY",
+  apiKey: "YOUR_PROJECT_API_KEY",
   multiTabMode: "leader"
 });
 ```
 
-One tab becomes the sender and reduces duplicate traffic.
+Only one tab will send events.
 
 ---
 
-# Architecture
+# Manual Flush
 
+```ts
+await tracker.flush();
 ```
- Application
-     │
-     ▼
- Eventra SDK
-     │
- batching + retry
-     │
-     ▼
- Eventra Ingest API
-     │
- idempotent pipeline
-     │
-     ▼
- Eventra Event Store
+
+---
+
+# Shutdown / Cleanup
+
+```ts
+tracker.destroy();
 ```
 
+Stops timers and prevents further event sending.
+
 ---
 
-# Best Practices
+# Runtime Support
 
-Use semantic event names.
+Eventra SDK works in:
 
-Good:
+* Node.js
+* Browser
+* Bun
+* Deno
+* Edge runtimes
+* Serverless environments
 
-```
-invoice.created
-checkout.completed
-team.invited
+---
+
+# Event Format
+
+Events are sent in batches:
+
+```json
+{
+  "sentAt": "2026-03-12T10:00:00Z",
+  "sdk": {
+    "name": "@eventra_dev/eventra-sdk",
+    "version": "0.1.2",
+    "runtime": "node"
+  },
+  "events": [
+    {
+      "name": "user_signup",
+      "userId": "user_123",
+      "timestamp": "2026-03-12T10:00:00Z",
+      "properties": {}
+    }
+  ]
+}
 ```
 
-Bad:
+---
 
-```
-button_clicked
-modal_opened
-```
+# Error Handling
+
+Client errors (4xx) are **not retried**.
+
+Server errors (5xx) are retried using **exponential backoff**.
+
+---
+
+# Documentation
+
+Full documentation:
+
+https://eventra.dev/docs
 
 ---
 

package/dist/index.cjs

@@ -25,7 +25,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/client.ts
-var SDK_VERSION = "0.1.2";
+var SDK_VERSION = "0.1.4";
 var DEFAULTS = {
   endpoint: "http://api.eventra.dev/api/v1/ingest/batch",
   flushInterval: 2e3,

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/client.ts
-var SDK_VERSION = "0.1.2";
+var SDK_VERSION = "0.1.4";
 var DEFAULTS = {
   endpoint: "http://api.eventra.dev/api/v1/ingest/batch",
   flushInterval: 2e3,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventra_dev/eventra-sdk",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "private": false,
   "publishConfig": {
     "access": "public"