Upstack Node.js SDK

Server-side tracking SDK for Node.js applications. Send tracking events from your backend to the Upstack platform.

Installation

npm install upstack-node-js

Quick Start

import { Upstack } from 'upstack-node-js';

// Initialize the client with your pixel ID
const client = Upstack.init({
  pixelId: 'your-pixel-id',
});

// Track events
await client.track({
  name: 'purchase',
  data: {
    value: 99.99,
    currency: 'USD',
    orderId: 'order-123',
    items: [
      { id: 'prod-1', name: 'Widget', price: 99.99, quantity: 1 }
    ]
  }
});

// Identify users
await client.identify({
  identity: {
    traits: {
      emails: ['[email protected]'],
      firstNames: ['John'],
      lastNames: ['Doe']
    }
  }
});

API Reference

Upstack.init(config)

Initialize a new Upstack client.

const client = Upstack.init({
  pixelId: 'your-pixel-id',     // Required: Your Upstack pixel ID
  timeout: 10000,                // Optional: Request timeout in ms (default: 10000)
  debug: false                   // Optional: Enable debug logging (default: false)
});

client.track(options)

Send a tracking event.

await client.track({
  name: 'purchase',              // Required: Event name
  data: {                        // Optional: Event data
    value: 99.99,
    currency: 'USD',
    orderId: 'order-123',
    items: [...]
  },
  context: {                     // Optional: Event context
    identity: {
      traits: {
        emails: ['[email protected]']
      }
    }
  }
});

Standard Event Names

| Event Name | Description | |------------|-------------| | page_view | User viewed a page | | view_content | User viewed a product/content | | add_to_cart | User added item to cart | | initiate_checkout | User started checkout | | add_payment_info | User added payment information | | purchase | User completed purchase | | lead | User submitted a lead form | | sign_up | User signed up | | login | User logged in | | search | User performed a search |

client.identify(options)

Identify a user. This stores the identity context for all subsequent track() calls.

await client.identify({
  identity: {
    traits: {
      emails: ['[email protected]'],
      phones: ['+1234567890'],
      firstNames: ['John'],
      lastNames: ['Doe'],
      addresses: [{
        city: 'New York',
        country: 'US',
        zip: '10001'
      }]
    }
  },
  properties: {                  // Optional: Additional context
    campaign: {
      source: 'google',
      medium: 'cpc'
    }
  }
});

client.getContext()

Get the currently stored context.

const context = client.getContext();
console.log(context.identity?.traits?.emails);

client.clearContext()

Clear the stored context.

client.clearContext();

Event Data Reference

Purchase Event

await client.track({
  name: 'purchase',
  data: {
    orderId: 'order-123',
    value: 149.99,
    currency: 'USD',
    tax: 12.50,
    shipping: 5.99,
    discount: 10.00,
    coupon: 'SAVE10',
    items: [
      {
        id: 'prod-123',
        name: 'Premium Widget',
        sku: 'WIDGET-001',
        price: 149.99,
        quantity: 1,
        category: 'Electronics',
        brand: 'WidgetCo'
      }
    ]
  }
});

Add to Cart Event

await client.track({
  name: 'add_to_cart',
  data: {
    value: 29.99,
    currency: 'USD',
    items: [
      {
        id: 'prod-456',
        name: 'Basic Gadget',
        price: 29.99,
        quantity: 1
      }
    ]
  }
});

Error Handling

The SDK throws UpstackError for all errors:

import { Upstack, UpstackError } from 'upstack-node-js';

try {
  await client.track({ name: 'purchase', data: { value: 99.99 } });
} catch (error) {
  if (error instanceof UpstackError) {
    console.error('Upstack error:', error.message);
    console.error('Error code:', error.code);       // e.g., 'NETWORK_ERROR', 'TIMEOUT'
    console.error('Status code:', error.statusCode); // HTTP status if applicable
  }
}

Error Codes

| Code | Description | |------|-------------| | INVALID_CONFIG | Invalid client configuration | | NETWORK_ERROR | Network request failed | | TIMEOUT | Request timed out | | TRACK_FAILED | Failed to track event | | IDENTIFY_FAILED | Failed to identify user |

TypeScript Support

The SDK is written in TypeScript and includes full type definitions:

import { 
  Upstack, 
  UpstackClient,
  TrackingEvent,
  TrackingEventData,
  EventContext,
  EventIdentity,
  ClientConfig,
  TrackOptions,
  IdentifyOptions
} from 'upstack-node-js';

Environment Configuration

The SDK reads process.env.STAGE at runtime to select the API URL:

| Stage | API URL | |-------|---------| | dev2 | https://dev2-api.upstackdata.io | | qa2 | https://qa2-api.upstackdata.io | | prod2 (default) | https://cfapi.upstackdata.io |

If STAGE is not set, the SDK defaults to prod2.

Requirements

• Node.js >= 20.0.0
• Native fetch support (Node.js 18+ or polyfill)

License

MIT