npm package: @hokuspokus/booking-sdk
Description: TypeScript SDK for ZvenBook booking system API
Author: ZvenBook
Latest version: 1.0.0

# @zvenbook/booking-sdk

A TypeScript SDK for integrating with the ZvenBook booking system API. This SDK provides a type-safe interface for managing bookings, services, providers, and availability in your applications.

## Installation

```bash
npm install @zvenbook/booking-sdk
```

```bash
yarn add @zvenbook/booking-sdk
```

```bash
pnpm add @zvenbook/booking-sdk
```

## Quick Start

```ts
import { createSdk } from '@zvenbook/booking-sdk';

// Initialize the SDK with your API endpoint
const sdk = createSdk({
  baseUrl: 'https://your-api.zvenbook.com', // Replace with your API URL
});

// Check API health
await sdk.health();

// List available services
const { services } = await sdk.listServices({ tenantId: 'your-tenant-id' });

// List providers
const { providers } = await sdk.listProviders({ tenantId: 'your-tenant-id' });

// Check availability
const { slots } = await sdk.availability({
  tenantId: 'your-tenant-id',
  serviceId: 'service-id',
  providerId: 'provider-id',
  start: new Date().toISOString(),
  end: new Date(Date.now() + 3600_000).toISOString(),
  timezone: 'Europe/Stockholm',
});
```

## Configuration

The SDK requires a configuration object with the following properties:

```ts
interface SdkConfig {
  baseUrl: string; // Your ZvenBook API endpoint
  fetch?: typeof fetch; // Optional custom fetch implementation
}
```

## API Reference

### Core Methods

#### Health Check

```ts
await sdk.health();
// Returns: { ok: true }
```

#### Services Management

```ts
// List services
const { services } = await sdk.listServices({ tenantId: string });

// Create service
const service = await sdk.createService({
  tenantId: string,
  name: string,
  durationMin: number,
  bufferBeforeMin?: number,
  bufferAfterMin?: number,
  capacity?: number
});

// Update service
await sdk.updateService(id: string, updates: Partial<ServiceInput>);

// Delete service
await sdk.deleteService(id: string);
```

#### Providers Management

```ts
// List providers
const { providers } = await sdk.listProviders({ tenantId: string });

// Create provider
const provider = await sdk.createProvider({
  tenantId: string,
  name: string,
  timezone: string,
  email?: string
});

// Update provider
await sdk.updateProvider(id: string, updates: Partial<ProviderInput>);

// Delete provider
await sdk.deleteProvider(id: string);
```

#### Availability & Booking

```ts
// Check availability
const { slots } = await sdk.availability({
  tenantId: string,
  serviceId: string,
  providerId: string,
  start: string,    // ISO date string
  end: string,      // ISO date string
  timezone: string
});

// Service availability (across all providers)
const { serviceAvailability } = await sdk.serviceAvailability({
  tenantId: string,
  providerId?: string,
  start: string,
  end: string,
  timezone: string
});

// Create booking
const result = await sdk.createBooking({
  tenantId: string,
  serviceId: string,
  providerId: string,
  start: string,
  end: string,
  status?: 'confirmed' | 'pending' | 'blocked',
  contactEmail?: string,
  contactFirstName?: string,
  contactLastName?: string,
  contactPhone?: string,
  notes?: string,
  consentAt?: string
});

// List bookings
const { bookings } = await sdk.listBookings({
  tenantId: string,
  providerId?: string
});

// Delete booking
await sdk.deleteBooking(id: string, tenantId?: string);
```

#### Weekly Rules Management

```ts
// Create weekly rule
const rule = await sdk.createWeeklyRule({
  tenantId: string,
  providerId: string,
  timezone: string,
  days: Array<{ weekday: number; start: string; end: string }>
});

// Update weekly rule
await sdk.updateWeeklyRule(id: string, updates: Partial<WeeklyRuleInput>);

// Delete weekly rule
await sdk.deleteWeeklyRule(id: string);

// List weekly rules
const { rule } = await sdk.listWeeklyRules({
  tenantId: string,
  providerId: string
});
```

#### Provider-Service Relationships

```ts
// List provider-service relationships
const { providerServices } = await sdk.listProviderServices({
  providerId?: string,
  serviceId?: string
});

// Add provider to service
await sdk.addProviderService({
  providerId: string,
  serviceId: string
});

// Remove provider from service
await sdk.removeProviderService(providerId: string, serviceId: string);
```

#### Analytics

```ts
// Get provider workload
const { providers } = await sdk.getProviderWorkload({
  tenantId: string,
  start: string,
  end: string,
});
```

## Error Handling

The SDK throws errors for failed API calls. Always wrap SDK calls in try-catch blocks:

```ts
try {
  const { slots } = await sdk.availability({
    tenantId: 'tenant-id',
    serviceId: 'service-id',
    providerId: 'provider-id',
    start: new Date().toISOString(),
    end: new Date(Date.now() + 3600_000).toISOString(),
    timezone: 'Europe/Stockholm',
  });
  console.log('Available slots:', slots);
} catch (error) {
  console.error('Failed to fetch availability:', error.message);
}
```

## TypeScript Support

This SDK is written in TypeScript and provides full type definitions. All methods and their parameters are fully typed for better development experience.

## Browser Support

The SDK works in both Node.js and browser environments. For browser usage, make sure your build tool supports ES modules or use a bundler like Webpack, Vite, or Rollup.

## License

MIT

## Support

For support and questions, please visit our [GitHub repository](https://github.com/your-org/booking-system) or contact us at support@zvenbook.com.