Package Exports

@session-services/sdk
@session-services/sdk/analytics
@session-services/sdk/analytics/react
@session-services/sdk/contract
@session-services/sdk/schemas

Readme

@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: 'user@example.com' });
  }, [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:

Session Services - All events are sent to the Session Services analytics backend
Facebook Pixel - If promoter has fbId configured
Google Tag Manager - If promoter has gtmId configured
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