@eventra_dev/eventra-sdk 0.1.2 → 0.1.3

package/README.md

@@ -1,194 +1,248 @@
 # 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 (Node.js / Browser / Bun / Deno)
+* resilient (batching + retry)
+* production-safe
 
 ---
 
-##  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"
+const eventra = new Eventra({
+  apiKey: "your-api-key",
+  endpoint: "https://api.eventra.dev/api/v1/events"
 });
 
-tracker.track("checkout.completed", {
-  userId: "user_123"
+eventra.track("user_signup", {
+  userId: "user_123",
+  properties: {
+    plan: "pro"
+  }
 });
 ```
 
 ---
 
-## Node / NestJS
+# Basic Usage
 
 ```ts
-import { Eventra } from "@eventra/sdk";
+import { Eventra } from "@eventra_dev/eventra-sdk";
 
-const tracker = new Eventra({
-  apiKey: process.env.EVENTRA_API_KEY!
+const client = new Eventra({
+  apiKey: "your-api-key",
+  endpoint: "https://api.eventra.dev/api/v1/events"
 });
 
-tracker.track("invoice.created", {
-  userId: "user_123"
+client.track("project_created", {
+  userId: "user_1",
+  properties: {
+    projectId: "proj_123"
+  }
 });
 ```
 
----
+Events are automatically:
+
+* batched
+* retried
+* flushed periodically
 
-#  Configuration
+---
 
-| Option | Default |
-|------|------|
-| flushInterval | 2000 ms |
-| maxBatchSize | 50 |
-| maxRetries | 3 |
-| maxQueueSize | 10000 |
-| retryBaseDelayMs | 300 |
+# Configuration
 
-Example:
+You can configure the SDK behaviour:
 
 ```ts
-const tracker = new Eventra({
-  apiKey: "API_KEY",
+const eventra = new Eventra({
+  apiKey: "your-api-key",
+
+  endpoint: "https://api.eventra.dev/api/v1/events",
+
   flushInterval: 2000,
-  maxBatchSize: 50
+  maxBatchSize: 50,
+  maxQueueSize: 10000,
+  maxRetries: 3
 });
 ```
 
+### 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 |
+
 ---
 
-# Reliability Model
+# Browser Usage
 
-### Idempotency
+```ts
+import { Eventra } from "@eventra_dev/eventra-sdk";
 
-Each event receives a **UUID v4 idempotency key**, ensuring:
+const eventra = new Eventra({
+  apiKey: "public-api-key",
+  endpoint: "https://api.eventra.dev/api/v1/events"
+});
 
-- safe retries
-- duplicate suppression
-- multi-tab safety
+eventra.track("page_view", {
+  properties: {
+    path: window.location.pathname
+  }
+});
+```
 
----
+The SDK automatically:
 
-### Retry Policy
+* batches events
+* retries failed requests
+* flushes on page exit
 
-The SDK retries only when safe:
+---
 
-✔ network failures  
-✔ HTTP 5xx
+# Node.js Usage
 
-It does **not retry**:
+```ts
+import { Eventra } from "@eventra_dev/eventra-sdk";
+
+const eventra = new Eventra({
+  apiKey: process.env.EVENTRA_API_KEY!,
+  endpoint: "https://api.eventra.dev/api/v1/events"
+});
 
-✖ HTTP 4xx  
-✖ validation errors  
-✖ authentication errors
+eventra.track("job_completed", {
+  properties: {
+    duration: 120
+  }
+});
+```
 
 ---
 
-### Backoff Strategy
+# Multi-tab Mode (Browser)
 
+To avoid duplicate event sending across multiple tabs you can enable leader mode:
+
+```ts
+const eventra = new Eventra({
+  apiKey: "your-api-key",
+  multiTabMode: "leader"
+});
 ```
-delay = base * 2^attempt * jitter(0.5–1.5) 
-```
+
+Only one tab will send events.
 
 ---
 
-# Multi-Tab Mode
+# Manual Flush
 
-Default:
+You can flush the queue manually:
 
 ```ts
-multiTabMode: "independent"
+await eventra.flush();
 ```
 
-Leader mode:
+---
+
+# Shutdown / Cleanup
 
 ```ts
-const tracker = new Eventra({
-  apiKey: "API_KEY",
-  multiTabMode: "leader"
-});
+eventra.destroy();
 ```
 
-One tab becomes the sender and reduces duplicate traffic.
+Stops timers and prevents further event sending.
 
 ---
 
-# Architecture
+# Runtime Support
 
-```
- Application
-     │
-     ▼
- Eventra SDK
-     │
- batching + retry
-     │
-     ▼
- Eventra Ingest API
-     │
- idempotent pipeline
-     │
-     ▼
- Eventra Event Store
+The SDK works in:
+
+* Node.js
+* Browser
+* Bun
+* Deno
+* Edge runtimes
+
+---
+
+# 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": {}
+    }
+  ]
+}
 ```
 
 ---
 
-# Best Practices
+# Error Handling
 
-Use semantic event names.
+Client errors (4xx) are **not retried**.
+Server errors (5xx) are retried with **exponential backoff**.
 
-Good:
+---
 
-```
-invoice.created
-checkout.completed
-team.invited
-```
+# Documentation
 
-Bad:
+Full documentation:
 
-```
-button_clicked
-modal_opened
-```
+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.3";
 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.3";
 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.3",
   "private": false,
   "publishConfig": {
     "access": "public"