@vitalwall/client/README.md

VitalWall client library for vanilla JavaScript applications

# @vitalwall/client

A JavaScript client library for [VitalWall](https://vitalwall.com) that allows you to integrate real-time wall displays and programmatically add items to your walls.

> 🌐 **Visit [VitalWall.com](https://vitalwall.com)** to create your account, get API keys, and manage your walls.

## What is VitalWall?

**VitalWall** is a real-time activity wall service that helps businesses showcase live user interactions, sales, signups, and other activities on their websites. Think of it as a "social proof engine" that displays real-time notifications to boost user engagement and conversions.

### 🎯 **Use Cases**

**E-commerce & Sales:**
- "John from New York just purchased Premium Plan - $299"
- "Sarah completed checkout for Wireless Headphones"
- "5 people viewing this product right now"

**SaaS & Apps:**
- "Welcome Alex! Just signed up from California" 
- "ProjectManager Pro upgrade by TechCorp Inc."
- "1,247 tasks completed today across all users"

**Events & Webinars:**
- "Michael just registered for tomorrow's webinar"
- "LiveStream starting in 5 minutes - 234 attendees ready"
- "Q&A session: 'Great question from Jennifer in Miami'"

**General Business:**
- "New review: ⭐⭐⭐⭐⭐ 'Excellent service!' - David"
- "Newsletter signup from Berlin, Germany"
- "Support ticket resolved in 2 minutes"

### ✨ **Why Use VitalWall?**

- **🚀 Increase Conversions**: Social proof encourages action
- **⚡ Real-time Updates**: Live activity creates urgency
- **🎨 Customizable**: Match your brand and design
- **📱 Responsive**: Works on desktop, tablet, and mobile
- **🔧 Easy Integration**: Add with just a few lines of code
- **📊 Analytics Ready**: Track engagement and performance

### 🌟 **How It Works**

1. **Track Events**: Use this library to send user activities to VitalWall
2. **Display Live**: VitalWall renders real-time notifications on your site
3. **Engage Users**: Visitors see live activity and are encouraged to take action
4. **Boost Results**: Increased social proof leads to higher conversions

**Example Flow:**
```
User Action → VitalWall.addItem() → Real-time Display → Increased Engagement
```

### 🛠️ **Library Features**

- **🔄 Real-time Communication**: WebSocket-based live updates
- **📦 Multiple Formats**: Support for text and HTML content
- **🎯 Multi-Wall Support**: Manage different walls for different purposes
- **🔒 Secure**: Automatic domain validation and API key authentication
- **⚡ Lightweight**: Minimal footprint with zero dependencies
- **🌐 Universal**: Works in browsers and Node.js environments
- **🎨 Auto-Tracking**: Optional data-attribute based tracking
- **📱 Responsive**: Mobile-friendly wall displays

### 🏢 **Perfect For**

- **E-commerce stores** wanting to show live purchases
- **SaaS companies** displaying user signups and upgrades  
- **Event organizers** showing live registrations
- **Service businesses** highlighting reviews and testimonials
- **Any website** wanting to add social proof and urgency

---

---

## 🚀 Get Started with VitalWall

1. **📝 Create Account**: Visit [VitalWall.com](https://vitalwall.com) to sign up
2. **🔑 Get API Key**: Generate your API credentials in the dashboard
3. **🏗️ Create Wall**: Set up your first wall and get the wall ID
4. **💻 Install Library**: Follow the Quick Start below to integrate

---

## Quick Start

Get VitalWall running on your site in 3 steps:

### 1. Install & Initialize
```bash
npm install @vitalwall/client
```

```javascript
import VitalWall from '@vitalwall/client';

const vitalWall = new VitalWall();
await vitalWall.init({
  apiKey: 'your-api-key',  // Get from VitalWall dashboard
  wallId: 'your-wall-id'   // Create in VitalWall dashboard
});
```

### 2. Add Display Container
```html
<!-- This div will show your real-time activity -->
<div data-vital-wall="your-wall-id" style="height: 400px;"></div>
```

### 3. Track Events
```javascript
// When someone makes a purchase
await vitalWall.addTextItem('New sale: Premium Plan - $99');

// When someone signs up  
await vitalWall.addHtmlItem(`
  <strong>Welcome!</strong> ${userName} just joined from ${city}
`);
```

**That's it!** Your wall will now display real-time activity to boost engagement and conversions.

> 💡 **Need an API key?** Visit [VitalWall.com](https://vitalwall.com) to create your free account and get your API credentials.

---

## Installation

```bash
npm install @vitalwall/client
```

## Detailed Usage

> 💡 **New to VitalWall?** Check the [Quick Start](#quick-start) section above for a simple 3-step setup.

### Basic Setup

> 🔑 **Getting Your Credentials**: Sign up at [VitalWall.com](https://vitalwall.com) to get your `apiKey` and create walls to get `wallId` values.

```javascript
import VitalWall from '@vitalwall/client';

const vitalWall = new VitalWall();

// Initialize with your API key
await vitalWall.init({
  apiKey: 'your-api-key',
  wallId: 'your-wall-id', // Optional: set default wall
  debug: true // Optional: enable debug logging
});
```

### HTML Wall Display

Add a wall display to your HTML:

```html
<div data-vital-wall="your-wall-id" style="height: 400px;"></div>
```

The wall will automatically initialize and display real-time updates.

### Adding Items Programmatically

```javascript
// Add a text item to the current wall
const itemId = await vitalWall.addTextItem('New user signed up!');

// Add an HTML item to a specific wall
const itemId = await vitalWall.addHtmlItem(
  '<div><strong>Sale!</strong> User purchased Product X</div>',
  'specific-wall-id'
);

// Add a custom item
const itemId = await vitalWall.addItem({
  content: 'Custom content',
  isHtml: false,
  wallId: 'wall-id' // Optional, uses current wall if not specified
});
```

### Wall Management

```javascript
// Set the current wall (for addItem methods without wallId)
vitalWall.setCurrentWall('new-wall-id');

// Get the current wall ID
const currentWall = vitalWall.getCurrentWall();

// Check if VitalWall is initialized
if (vitalWall.isInitialized()) {
  // Ready to use
}

// Listen for initialization completion
vitalWall.onReady(() => {
  console.log('VitalWall is ready!');
  // Add items, etc.
});
```

### Automatic Tracking (Legacy Compatibility)

VitalWall also supports automatic tracking of user interactions using data attributes, maintaining compatibility with the script tag version:

```html
<!-- Track clicks on this button -->
<button data-vital-item="User clicked signup button">Sign Up</button>

<!-- Auto-track when element appears (no click required) -->
<div data-vital-item="Page loaded" data-vital-auto="true"></div>

<!-- Track with HTML content -->
<div data-vital-item="Rich content" data-vital-html="true">
  <strong>User Action:</strong> Downloaded PDF
</div>

<!-- Send content from another element -->
<div id="user-info">John Doe purchased Product X</div>
<button data-vital-send-content="user-info">Track Purchase</button>
```

### Configuration Options

```javascript
await vitalWall.init({
  apiKey: 'your-api-key',           // Required: Your VitalWall API key
  wallId: 'default-wall-id',        // Optional: Default wall ID for addItem methods
  debug: true,                      // Optional: Enable debug logging
  domain: 'example.com'             // Optional: Only for Node.js environments (auto-detected in browsers)
});
```

**Security Note**: The `domain` parameter is automatically detected from `window.location.hostname` in browser environments for security purposes. It should only be manually specified when using VitalWall in Node.js server environments.

### Cleanup

```javascript
// Clean up all walls and event listeners
vitalWall.cleanup();
```

## Examples

### E-commerce Site

```javascript
import VitalWall from '@vitalwall/client';

const vitalWall = new VitalWall();

await vitalWall.init({
  apiKey: 'your-api-key',
  wallId: 'sales-wall'
});

// Track purchases
document.getElementById('purchase-btn').addEventListener('click', async () => {
  const product = getCurrentProduct();
  await vitalWall.addHtmlItem(`
    <div class="purchase-notification">
      <strong>${product.name}</strong> purchased by ${user.name}
      <span class="price">$${product.price}</span>
    </div>
  `);
});
```

### Real-time Dashboard

```javascript
import VitalWall from '@vitalwall/client';

const vitalWall = new VitalWall();

await vitalWall.init({
  apiKey: 'your-api-key'
});

// Multiple walls for different metrics
const salesWall = 'sales-wall-id';
const signupsWall = 'signups-wall-id';

// Track different events to different walls
await vitalWall.addTextItem('New sale: $299', salesWall);
await vitalWall.addTextItem('New user registered', signupsWall);
```

## More Examples

For additional comprehensive examples including e-commerce integration, real-time dashboards, and lifecycle management, see the [examples.ts](./examples.ts) file in this package.

### Node.js Server Example

For server-side usage with Express.js middleware, batch operations, and programmatic item tracking, see the complete Node.js example at [examples/nodejs-server.mjs](./examples/nodejs-server.mjs).

The Node.js example demonstrates:
- Server-side VitalWall initialization with domain validation
- Express.js middleware integration
- Batch event processing
- E-commerce order tracking
- User registration notifications
- System alert monitoring

## API Reference

For complete API documentation with detailed method signatures, error handling, and type definitions, see [API.md](./API.md).

### VitalWall Class

#### Methods

- `init(config: VitalWallConfig): Promise<void>` - Initialize VitalWall
- `addItem(item: WallItem): Promise<string | undefined>` - Add a custom item
- `addTextItem(content: string, wallId?: string): Promise<string | undefined>` - Add text item
- `addHtmlItem(content: string, wallId?: string): Promise<string | undefined>` - Add HTML item
- `setCurrentWall(wallId: string): void` - Set default wall ID
- `getCurrentWall(): string | null` - Get current wall ID
- `isInitialized(): boolean` - Check initialization status
- `onReady(callback: () => void): void` - Add ready callback
- `cleanup(): void` - Clean up resources

### Types

```typescript
interface VitalWallConfig {
  apiKey: string;
  debug?: boolean;
  wallId?: string;
  domain?: string; // For Node.js environments only
}

interface WallItem {
  content: string;
  isHtml?: boolean;
  wallId?: string;
}
```

## Browser Support

- Chrome/Edge 60+
- Firefox 55+
- Safari 10.1+
- IE 11+ (with polyfills)

## License

MIT