@vennio/sdk

Add scheduling to your app in minutes. The Vennio SDK makes it easy to integrate booking functionality without dealing with calendar OAuth, availability calculations, or timezone complexity.

Installation

npm install @vennio/sdk

Quick Start

import { Vennio } from '@vennio/sdk'

// Initialize with your publishable key
const vennio = new Vennio('pk_live_your_key_here')

// Get available time slots
const slots = await vennio.getSlots({
  duration: 30,  // 30 minute appointments
  days: 14       // Look 2 weeks ahead
})

// Book a slot
const booking = await vennio.book(slots[0], {
  email: '[email protected]',
  name: 'Jane Smith'
})

console.log('Booked!', booking.id)

API Reference

new Vennio(apiKey, config?)

Create a new Vennio client.

const vennio = new Vennio('pk_live_xxx', {
  baseUrl: 'https://api.vennio.app',  // Optional, defaults to production
  timeout: 30000                       // Optional, request timeout in ms
})

vennio.getSlots(options)

Get available time slots.

const slots = await vennio.getSlots({
  duration: 30,           // Required: appointment length in minutes
  days: 14,               // Optional: days to look ahead (default: 14)
  from: '2024-01-15',     // Optional: start date (default: now)
  to: '2024-01-30',       // Optional: end date
  timezone: 'America/New_York'  // Optional: timezone (default: local)
})

// Returns:
[
  {
    start: '2024-01-15T09:00:00Z',
    end: '2024-01-15T09:30:00Z',
    duration: 30,
    available: true
  },
  // ...more slots
]

vennio.book(slot, customer)

Book a time slot.

const booking = await vennio.book(slots[0], {
  email: '[email protected]',  // Required
  name: 'Jane Smith',              // Required
  notes: 'Looking forward to it!', // Optional
  metadata: { source: 'website' }  // Optional
})

// Returns:
{
  id: 'bk_abc123',
  status: 'confirmed',
  start_time: '2024-01-15T09:00:00Z',
  end_time: '2024-01-15T09:30:00Z',
  customer: {
    email: '[email protected]',
    name: 'Jane Smith'
  },
  created_at: '2024-01-10T12:00:00Z',
  calendar_links: {
    google: 'https://calendar.google.com/...',
    outlook: 'https://outlook.live.com/...',
    ical: 'data:text/calendar;...'
  }
}

vennio.getBooking(bookingId)

Get booking details.

const booking = await vennio.getBooking('bk_abc123')

vennio.cancelBooking(bookingId, reason?)

Cancel a booking.

const booking = await vennio.cancelBooking('bk_abc123', 'Customer requested')

Error Handling

The SDK throws VennioError for all errors:

try {
  const slots = await vennio.getSlots({ duration: 30 })
} catch (error) {
  if (error.code === 'unauthorized') {
    console.log('Invalid API key')
  } else if (error.code === 'rate_limit_exceeded') {
    console.log('Too many requests, try again later')
  } else {
    console.log('Error:', error.message)
  }
}

TypeScript Support

Full TypeScript support with exported types:

import { Vennio, Slot, Booking, Customer, VennioError } from '@vennio/sdk'

Get Your API Key

1. Sign up at vennio.app/get-started
2. Connect your calendar
3. Copy your publishable key

Support

• Documentation: docs.vennio.app
• Issues: github.com/vennio-app/vennio/issues