@session-services/sdk

Official JavaScript/TypeScript SDK for the Session Services API.

Installation

npm install @session-services/sdk

Browser Bundlers

Bundlers that honor the package browser export condition automatically use the browser-safe build for the root import. The explicit browser entry point is also available when you want to guarantee that selection:

import { createClient } from '@session-services/sdk/browser';

CDN Usage

Use directly in browsers via unpkg:

<script type="module">
  import { createClient } from 'https://unpkg.com/@session-services/sdk@latest/dist/browser.mjs';

  const client = createClient({
    environment: 'prod',
    tenantId: 'your-tenant-id'
  });

  const { event } = await client.event.get({ key: 'event-slug' });
</script>

Pin @latest to an exact SDK version in production.

Quick Start

import { createClient } from '@session-services/sdk';

const client = createClient({
  environment: 'sandbox',
  tenantId: 'your-tenant-id'
});

const { event } = await client.event.get({ key: 'event-slug' });

Configuration

| Option | Type | Description | |--------|------|-------------| | environment | 'sandbox' \| 'prod' \| string | API environment or custom URL | | tenantId | string | Tenant ID (defaults to Session Services) | | headers | Record<string, string> | Additional request headers |

const client = createClient({
  environment: 'prod',
  tenantId: 'your-tenant-id',
  headers: { 'X-Custom-Header': 'value' }
});

API Reference

Full API documentation: https://api.session.services/docs

The client provides typed methods matching the API structure:

// Pattern: client.{resource}.{method}({ ...params })
await client.event.get({ key: 'event-id' });
await client.event.list({});
await client.order.get({ key: 'order-id' });

React Query Integration

import { createQueryClient } from '@session-services/sdk';
import { QueryClientProvider, QueryClient } from '@tanstack/react-query';

const queryClient = new QueryClient();
const api = createQueryClient({
  environment: 'prod',
  tenantId: 'your-tenant-id'
});

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <EventList />
    </QueryClientProvider>
  );
}

function EventList() {
  const { data } = api.event.list.useQuery({});
  return <ul>{data?.items.map(e => <li key={e.id}>{e.name}</li>)}</ul>;
}

Analytics

The SDK includes analytics for tracking events to Session Services and third-party pixels (Facebook, Google Analytics, TikTok).

Analytics monetary fields (price, value, total, revenue, and product price) use major currency units, not minor units. For example, send 99.00 for USD 99.00. The formatPrice utility below is for display and accepts minor units.

Vanilla JavaScript

import { createClient } from '@session-services/sdk';
import { createAnalytics } from '@session-services/sdk/analytics';

const client = createClient({ environment: 'prod', tenantId: '...' });
const analytics = createAnalytics({ client, debug: true });

// Track events
analytics.track('Product Viewed', {
  promoter_id: 'prm_123',
  event_id: 'evt_456',
  product_id: 'tkt_abc',
  name: 'VIP Ticket',
  price: 99.00,
  currency: 'USD'
});

// Page views
analytics.page('Event Page', { promoter_id: 'prm_123' });

// Identify users
analytics.identify('user_123', { promoter_id: 'prm_123' });

// Reset session (e.g., on logout)
analytics.reset();

React Hooks

import { createClient } from '@session-services/sdk';
import { AnalyticsProvider } from '@session-services/sdk/analytics/react';

const client = createClient({ environment: 'prod', tenantId: '...' });

function App() {
  return (
    <AnalyticsProvider client={client} debug={false}>
      <TicketPage />
    </AnalyticsProvider>
  );
}

useTrack

Track custom events:

import { useTrack } from '@session-services/sdk/analytics/react';

function AddToCartButton() {
  const track = useTrack();

  const handleClick = () => {
    track('Product Added', {
      promoter_id: 'prm_123',
      event_id: 'evt_456',
      product_id: 'tkt_abc',
      price: 99.00
    });
  };

  return <button onClick={handleClick}>Add to Cart</button>;
}

usePageView

Automatic page view tracking:

import { usePageView } from '@session-services/sdk/analytics/react';

function EventPage() {
  usePageView('Event Page', { promoter_id: 'prm_123', event_id: 'evt_456' });

  return <div>Event content...</div>;
}

useIdentify

Identify users after login:

import { useIdentify } from '@session-services/sdk/analytics/react';

function LoginSuccess({ userId }) {
  const identify = useIdentify();

  useEffect(() => {
    identify(userId, { promoter_id: 'prm_123', email: '[email protected]' });
  }, [userId]);
}

useReset

Reset session on logout:

import { useReset } from '@session-services/sdk/analytics/react';

function LogoutButton() {
  const reset = useReset();
  return <button onClick={reset}>Logout</button>;
}

useAnalytics

Direct access to all analytics methods:

import { useAnalytics } from '@session-services/sdk/analytics/react';

function MyComponent() {
  const analytics = useAnalytics();

  // Access all methods: track, page, screen, identify, reset, group, alias
  analytics?.track('Custom Event', { promoter_id: 'prm_123' });
}

Standard Events

| Event | Description | Required Properties | |-------|-------------|---------------------| | Product Viewed | User viewed a ticket/product | promoter_id, product_id, name, price | | Product Added | Added to cart | promoter_id, product_id, price, quantity | | Checkout Started | Began checkout flow | promoter_id, products, total, currency | | Order Completed | Purchase complete | promoter_id, order_id, total, currency, products |

All events require promoter_id to route analytics to the correct destinations. Use major currency units for monetary analytics properties. Use minor units only with formatPrice and internal ticketing price breakdown fields such as price_base and price_booking_fee.

Pixel Integrations

Analytics automatically routes events to third-party pixels based on promoter configuration:

1. Session Services - All events are sent to the Session Services analytics backend
2. Facebook Pixel - If promoter has fbId configured
3. Google Analytics - If promoter has gaId configured
4. TikTok Pixel - If promoter has tikTokId configured

The SDK fetches promoter pixel configuration automatically using the promoter_id in your event properties. No additional setup required.

Utilities

formatPrice

Format prices from minor units to localized currency strings:

import { formatPrice } from '@session-services/sdk/analytics';

formatPrice(9900, 'USD');  // "$99.00"
formatPrice(9900, 'EUR');  // "99,00 €"
formatPrice(9900, 'GBP');  // "£99.00"
formatPrice(9900, 'AUD');  // "$99.00"

Error Handling

import { safe, isDefinedError } from '@session-services/sdk';

const [error, result] = await safe(client.event.get({ key: 'event-id' }));

if (isDefinedError(error)) {
  console.error(`API Error [${error.code}]:`, error.message);
} else if (error) {
  console.error('Network error:', error.message);
} else {
  console.log(result.event.name);
}

Entry Points

| Import | Description | |--------|-------------| | @session-services/sdk | Client creation, error utilities | | @session-services/sdk/browser | Explicit browser-safe client build | | @session-services/sdk/analytics | Vanilla analytics (createAnalytics, formatPrice) | | @session-services/sdk/analytics/react | React hooks (AnalyticsProvider, useTrack, usePageView, useIdentify, useReset, useAnalytics) | | @session-services/sdk/schemas | Public Zod schemas for validation | | @session-services/sdk/contract | Public oRPC contract |

TypeScript

The package includes declarations, declaration maps, and their matching source files so editor navigation can inspect the underlying contract and schemas. API inputs and responses are inferred directly from the contract:

import type { AppClient, AppContract } from '@session-services/sdk';
import type { Analytics, EventProperties } from '@session-services/sdk/analytics';

Use @session-services/sdk/schemas to inspect or import the curated public Zod schema surface, and @session-services/sdk/contract when integrating directly with oRPC tooling. Internal service routes and schemas are intentionally not part of the published SDK contract.

Runtime Support

ES modules and CommonJS are supported on Node.js 20.19 or newer in the Node 20 line, and Node.js 22.12 or newer. Browser applications should use a modern bundler or the explicit browser/CDN entry points above.

License

MIT