@zvenbook/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.

Perfect for: Appointment scheduling, resource booking, service management, and time slot availability in any application.

Installation

npm install @zvenbook/sdk

yarn add @zvenbook/sdk

pnpm add @zvenbook/sdk

Quick Start

import { createSdk } from '@zvenbook/sdk';

// Initialize the SDK with your ZvenBook instance URL
const sdk = createSdk({
  baseUrl: 'https://your-zvenbook-instance.vercel.app', // Your deployed instance
  // baseUrl: 'http://localhost:3002',                  // Local development
});

// 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 (without /api suffix)
  fetch?: typeof fetch; // Optional custom fetch implementation
}

Important Notes

• API Endpoints: The SDK automatically appends /api to all endpoints. Your baseUrl should NOT include /api.
• Development: Use http://localhost:3002 for local development
• Production: Use your deployed ZvenBook instance URL (with https://)
• No Authentication: Most endpoints are public and don't require API keys

Migration from v1.0.1

If you're upgrading from v1.0.1, ensure your baseUrl does NOT include /api:

// ❌ Old (v1.0.1)
const sdk = createSdk({
  baseUrl: 'https://your-api.com/api', // Don't include /api
});

// ✅ New (v1.0.2+)
const sdk = createSdk({
  baseUrl: 'https://your-api.com', // SDK adds /api automatically
});

Tenant Management

All API calls require a tenantId parameter. This should be the actual tenant ID (not the slug):

// ✅ Correct - Use the actual tenant ID
const tenantId = 'tenant_1757893343516_qb6atfx4o';

// ❌ Incorrect - Don't use the slug
const tenantId = 'respicio'; // This is a slug, not an ID

To find your tenant ID, you can list all tenants:

const { tenants } = await sdk.listTenants();
const myTenant = tenants.find((t) => t.slug === 'respicio');
const tenantId = myTenant._id;

API Reference

Core Methods

Health Check

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

Tenant Management

// List all tenants
const { tenants } = await sdk.listTenants();

// Create a new tenant
const tenant = await sdk.createTenant({
  name: string,
  slug: string,
  email: string,
  website: string,
  timezone: string,
  settings: {
    allowOnlineBooking: boolean,
    requireEmailConfirmation: boolean,
    allowCancellation: boolean,
    cancellationWindowHours: number,
    reminderHours: number,
  },
});

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,
  organizationNumber?: 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].