npm package: @session-services/web-elements
Description: Framework-agnostic Web Components for [Session Services](https://session.services) ticketing.
Latest version: 0.1.20

# @session-services/web-elements

Framework-agnostic Web Components for [Session Services](https://session.services) ticketing.

## Installation

```bash
npm install @session-services/web-elements
```

The SDK is bundled, so no additional dependencies are required.

### CDN Usage

Use directly in browsers via unpkg (no build step required):

```html
<script type="module" src="https://unpkg.com/@session-services/web-elements"></script>

<session-services-ticketing
  tenant-id="your-tenant-id"
  event-id="evt_123"
  return-url="https://yoursite.com/order/complete"
></session-services-ticketing>
```

Custom elements are auto-registered when the script loads.

## Usage

```typescript
import { defineCustomElements } from '@session-services/web-elements/loader';

// Call once at app startup
defineCustomElements();
```

```html
<session-services-ticketing
  tenant-id="your-tenant-id"
  event-id="evt_123"
  return-url="https://yoursite.com/order/complete"
  theme="light"
></session-services-ticketing>
```

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `tenant-id` | `string` | Yes | — | Your Session Services tenant ID |
| `event-id` | `string` | Yes | — | Event ID to display tickets for |
| `api-url` | `string` | No | `https://api.session.services` | API endpoint URL |
| `locale` | `string` | No | `en-US` | Locale for formatting |
| `return-url` | `string` | No | — | URL to redirect after checkout |
| `theme` | `'light' \| 'dark' \| 'system'` | No | `system` | Color theme |
| `enable-analytics` | `boolean` | No | `true` | Enable analytics tracking |
| `debug-analytics` | `boolean` | No | `false` | Log analytics events to console |

## Events

Listen to events using standard DOM event listeners:

```javascript
const element = document.querySelector('session-services-ticketing');

element.addEventListener('cartUpdate', (e) => {
  console.log('Cart updated:', e.detail); // OrderQuote
});

element.addEventListener('checkoutInit', (e) => {
  const { orderId, checkoutUrl } = e.detail;
  window.location.href = checkoutUrl;
});

element.addEventListener('errorOccurred', (e) => {
  console.error('Error:', e.detail.error);
});
```

| Event | Detail Type | Description |
|-------|-------------|-------------|
| `cartUpdate` | `OrderQuote` | Fired when cart contents change |
| `checkoutInit` | `{ orderId: string; checkoutUrl: string }` | Fired when checkout begins |
| `errorOccurred` | `{ error: string }` | Fired on errors |

## Theming

Customize appearance with CSS variables:

```html
<session-services-ticketing
  tenant-id="..."
  event-id="..."
  style="
    --card: #fff;
    --card-foreground: #111827;
    --border: #e5e7eb;
    --primary: #ec4899;
    --primary-foreground: #ffffff;
    --accent: #f472b6;
    --accent-foreground: #0f172a;
    --secondary: #f3f4f6;
    --secondary-foreground: #1f2937;
    --muted-foreground: #6b7280;
    --ring: #f472b6;
  "
></session-services-ticketing>
```

## Framework Integration

Works with any framework - React, Vue, Angular, Svelte, or vanilla HTML.

For React, consider using `@session-services/react-elements` for better DX with typed props and event handlers.

## License

MIT