npm package: @session-services/sdk
Description: Official Session Services API SDK for JavaScript/TypeScript
Latest version: 0.1.20

# @session-services/sdk

Official JavaScript/TypeScript SDK for the Session Services API.

## Installation

```bash
npm install @session-services/sdk
```

### CDN Usage

Use directly in browsers via unpkg:

```html
<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

```typescript
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 |

```typescript
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:

```typescript
// 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

```typescript
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

```typescript
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

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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

```typescript
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:

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

## License

MIT