voltaire-sdk

Behavioral analytics SDK for Voltaire — tracks paywall events and user intent signals. Works in browsers (via the native Fetch API) and Node.js ≥ 18.

Installation

npm install @voltaire-sdk/web
# or
yarn add @voltaire-sdk/web
# or
pnpm add @voltaire-sdk/web

No external runtime dependencies — the SDK uses the native fetch API available in modern browsers and Node.js ≥ 18.

Quick start

import Voltaire from '@voltaire-sdk/web'

// 1. Initialise once at app startup
Voltaire.init({ apiKey: 'volt_xxx', category: 'productivity' })

// 2. (Optional) Set up automatic paywall triggers
//    After 2 uses of 'export_pdf', a paywall_shown event fires automatically
Voltaire.setPaywallTrigger({ feature: 'export_pdf', threshold: 2 })

// 3. Track events anywhere in your app
Voltaire.track('session_started')
Voltaire.track('feature_used', { feature: 'export_pdf' })
Voltaire.track('feature_gate_hit', { feature: 'export_pdf' })  // user hit premium gate
Voltaire.track('upgrade_clicked')                               // user tapped upgrade CTA
Voltaire.track('paywall_shown')
Voltaire.track('paywall_dismissed')
Voltaire.track('paywall_converted')

API Reference

Voltaire.init(options)

Initialises the SDK. Must be called before any other method.

| Option | Type | Required | Description | |------------|----------|----------|------------------------------------------------------| | apiKey | string | Yes | Your Voltaire API key (volt_xxx) | | category | string | No | App category label appended to every event | | apiUrl | string | No | Override the API base URL (default: https://mcp.hivoltaire.com) |

Voltaire.setPaywallTrigger(trigger)

Registers an automatic paywall trigger.

| Field | Type | Description | |-------------|----------|----------------------------------------------------------| | feature | string | Feature name to monitor | | threshold | number | Number of feature_used events before firing paywall_shown |

Voltaire.track(eventType, properties?)

Tracks an event. Fire-and-forget — always returns void, never throws.

Valid event types:

| Event type | Description | |----------------------|-----------------------------------------------------------------------------| | session_started | User session began | | session_ended | User session ended | | paywall_shown | Paywall was displayed | | paywall_dismissed | User dismissed the paywall | | paywall_converted | User subscribed / purchased | | feature_used | A specific feature was used | | feature_gate_hit | User hit a premium feature gate and was blocked — strongest intent signal | | upgrade_clicked | User tapped an upgrade / pricing CTA but did not complete payment |

Session ID

• Browser: A UUID is generated once and persisted in localStorage under the key voltaire_session_id. The same ID is reused across page reloads.
• Node.js: A UUID is generated once when init() is called and kept in memory for the process lifetime.

HTTP contract

Every call to track() sends:

POST https://mcp.hivoltaire.com/api/events
X-Api-Key: volt_xxx
Content-Type: application/json

{
  "event_type": "feature_used",
  "user_session_id": "<uuid>",
  "properties": { "feature": "export_pdf", "category": "productivity" }
}

All requests are non-blocking. Network errors are silently discarded.

Tree-shaking / named imports

import { init, track, setPaywallTrigger } from '@voltaire-sdk/web'

License

MIT