npm package: @keystone-symposia/ts-sdk
Description: TypeScript SDK for Keystone Symposia and Momentus APIs
Author: Keystone Symposia
Latest version: 1.0.6

# Keystone Symposia TypeScript SDK

A TypeScript SDK for interacting with Keystone Symposia and Momentus (Ungerboeck) APIs, designed for data extraction, ETL processes, and event management.

## Installation

```bash
npm install @keystonesymposia/ts-sdk
```

## Features

- 🎯 **Momentus API Client** - Full-featured client for Momentus/Ungerboeck API
- 📅 **Fiscal Year Utilities** - Helper functions for fiscal year calculations
- 🔄 **User-Defined Fields** - Parse and map custom fields to human-readable labels
- 📊 **ETL Support** - Built-in utilities for data extraction and transformation
- 🔒 **JWT Authentication** - Automatic JWT token generation and management
- 📝 **TypeScript Support** - Full TypeScript definitions included

## Quick Start

### Basic Setup

```typescript
import { MomentusClient } from '@keystonesymposia/ts-sdk';

// Initialize with environment variables
const client = new MomentusClient();

// Or provide configuration manually
const client = new MomentusClient({
  apiBaseUrl: 'https://your-instance.ungerboeck.net/api/v1',
  apiUserId: 'your-user-id',
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret'
});
```

### Environment Variables

Create a `.env` file:

```env
MOMENTUS_API_BASE_URL=https://your-instance.ungerboeck.net/api/v1
MOMENTUS_API_USER_ID=your-user-id
MOMENTUS_API_KEY=your-api-key
MOMENTUS_API_SECRET=your-api-secret
```

## Usage Examples

### Fetch Events by Fiscal Year

```typescript
import { MomentusClient, getFiscalYearDates } from '@keystonesymposia/ts-sdk';

const client = new MomentusClient();

// Get events for a specific fiscal year
const events = await client.getEventsByFiscalYear(2025);

// Get fiscal year date range
const fy2025 = getFiscalYearDates(2025);
console.log(fy2025);
// { year: 2025, startDate: '2024-07-16', endDate: '2025-07-15', label: 'FY25' }
```

### Expand User-Defined Fields

```typescript
// Fetch events with user-defined fields
const events = await client.getEventsByFiscalYear(2025);

// Expand the EventUserFieldSets JSON into individual columns
const expandedEvents = client.expandUserFieldsArray(events, 'EventUserFieldSets');

// Get field label mappings from API
const fieldLabels = await client.getUserDefinedFieldLabels('Z3');

// Apply labels to rename fields
const labeledEvents = client.applyUserFieldLabelsArray(expandedEvents, fieldLabels);
```

### Get Registrations

```typescript
// Get all registrations for an event
const registrations = await client.getEventRegistrations(12345);

// Get registration items
const items = await client.getRegistrationOrderItemsByEventId(12345);
```

### Work with Contacts and Accounts

```typescript
// Get contact by ID
const contact = await client.getContact('00012345');

// Search contacts
const contacts = await client.getContactsBySearch("LastName eq 'Smith'");

// Get account information
const account = await client.getAccountById(12345);
```

## API Reference

### MomentusClient

#### Event Methods
- `getEvent(eventId: number)` - Get a single event
- `getEventsByFiscalYear(year: number)` - Get events for a fiscal year
- `getEventsByDateRange(startDate: string, endDate: string)` - Get events in date range

#### Registration Methods
- `getEventRegistrations(eventId: number)` - Get all registrations for an event
- `getRegistrationOrderItemsByEventId(eventId: number)` - Get registration items

#### User-Defined Fields Methods
- `expandUserFields(obj: any, columnName: string)` - Expand user field sets JSON
- `getUserDefinedFieldLabels(issueOpportunityType: string)` - Get field mappings
- `applyUserFieldLabels(obj: any, fieldLabels: Record<string, string>)` - Apply labels

#### Contact/Account Methods
- `getContact(contactId: string)` - Get contact by ID
- `getContactsBySearch(searchStr: string)` - Search contacts
- `getAccount(accountId: string)` - Get account by ID
- `getAccountsBySearch(searchStr: string)` - Search accounts

### Fiscal Year Utilities

```typescript
import {
  getFiscalYearDates,
  getCurrentFiscalYear,
  getAvailableFiscalYears
} from '@keystonesymposia/ts-sdk';

// Get fiscal year info
const fy = getFiscalYearDates(2025);

// Get current fiscal year
const currentFY = getCurrentFiscalYear();

// Get available fiscal years (default: current ±2-3 years)
const availableFYs = getAvailableFiscalYears();
```

### User Fields Utilities

```typescript
import {
  expandUserFields,
  buildFieldLabelMapping,
  applyUserFieldLabels
} from '@keystonesymposia/ts-sdk';

// Expand user fields from JSON
const expanded = expandUserFields(event, 'EventUserFieldSets');

// Build mapping from API response
const mapping = buildFieldLabelMapping(fieldDefinitions);

// Apply labels
const labeled = applyUserFieldLabels(expanded, mapping);
```

## TypeScript Types

```typescript
import type {
  FiscalYear,
  MomentusEvent,
  MomentusRegistrationOrder,
  UserDefinedField
} from '@keystonesymposia/ts-sdk';
```

## ETL and Data Extraction

This SDK is optimized for ETL workflows:

1. **Extract** - Fetch data from Momentus API with built-in pagination and rate limiting
2. **Transform** - Expand and map user-defined fields to readable column names
3. **Load** - Export to CSV, database, or other destinations

Example ETL workflow:

```typescript
import { MomentusClient } from '@keystonesymposia/ts-sdk';

const client = new MomentusClient();

// Extract
const events = await client.getEventsByFiscalYear(2025);

// Transform
const expanded = client.expandUserFieldsArray(events, 'EventUserFieldSets');
const fieldLabels = await client.getUserDefinedFieldLabels('Z3');
const transformed = client.applyUserFieldLabelsArray(expanded, fieldLabels);

// Load (your choice - CSV, database, etc.)
console.log(`Extracted ${transformed.length} events`);
```

## Error Handling

```typescript
try {
  const events = await client.getEventsByFiscalYear(2025);
} catch (error) {
  console.error('Failed to fetch events:', error.message);
}
```

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Lint
npm run lint

# Clean build artifacts
npm run clean
```

## License

MIT © Keystone Symposia

## Support

For issues and questions:
- GitHub Issues: https://github.com/keystonesymposia/ts-sdk/issues
- Email: support@keystonesymposia.org