@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

npm install @zvenbook/booking-sdk

yarn add @zvenbook/booking-sdk

pnpm add @zvenbook/booking-sdk

Quick Start

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:

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

API Reference

Core Methods

Health Check

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

Services Management

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

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

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

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

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

// 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:

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 or contact us at [email protected].