@session-services/sdk

Official JavaScript/TypeScript SDK for the Session Services API.

Installation

npm install @session-services/sdk

CDN Usage

Use directly in browsers via unpkg:

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

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

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

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, GTM, TikTok).

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: 9900,
  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: 9900
    });
  };

  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.

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 Tag Manager - If promoter has gtmId 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 cents 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/analytics | Vanilla analytics (createAnalytics, formatPrice) | | @session-services/sdk/analytics/react | React hooks (AnalyticsProvider, useTrack, usePageView, useIdentify, useReset, useAnalytics) | | @session-services/sdk/schemas | Zod schemas for validation | | @session-services/sdk/contract | Raw oRPC contract |

TypeScript

Fully typed with inference from API responses:

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

License

MIT