@withaevum/sdk

TypeScript SDK for the Aevum API - a comprehensive scheduling and booking management platform.

Installation

npm install @withaevum/sdk
# or
yarn add @withaevum/sdk
# or
pnpm add @withaevum/sdk

Usage

Initialization

import { AevumClient } from '@withaevum/sdk';

const client = new AevumClient({
  apiKey: process.env.AEVUM_API_KEY,
  // Optional: customize base URL (default: https://withaevum.com)
  baseUrl: 'https://withaevum.com',
});

The SDK automatically resolves your organization ID from the API key, so you don't need to provide it manually.

API Reference

Bookings

Create a booking

const booking = await client.bookings.create({
  providerIds: ['provider_123'],
  offeringIds: ['offering_456'],
  startTime: '2024-01-15T10:00:00Z',
  endTime: '2024-01-15T10:30:00Z',
  customerEmail: '[email protected]',
  // Optional:
  // customerId: 'customer_789',
  // customer: { name: 'John Doe', email: '[email protected]', phone: '+1234567890' },
  // price_cents: 5000,
  // notes: 'Special request',
  // status: 'pending',
  // kind: 'standard',
});

Get a booking

const booking = await client.bookings.get('booking_123');

List bookings

const bookings = await client.bookings.list({
  providerId: 'provider_123',
  startDate: '2024-01-01T00:00:00Z',
  endDate: '2024-01-31T23:59:59Z',
  status: 'confirmed',
  page: 1,
  pageSize: 20,
});

Reschedule a booking

const updatedBooking = await client.bookings.reschedule('booking_123', {
  start_time: '2024-01-15T11:00:00Z', // Note: API uses snake_case for these fields
  end_time: '2024-01-15T11:30:00Z',
  sendNotification: true, // Optional, default: false
});

Cancel a booking

const cancelledBooking = await client.bookings.cancel(
  'booking_123',
  'Customer requested cancellation', // Optional reason
);

Confirm a booking

const confirmedBooking = await client.bookings.confirm('booking_123', {
  sendNotification: true, // Optional, default: false
});

Update a booking

const updatedBooking = await client.bookings.update('booking_123', {
  status: 'confirmed', // Optional: update status
  notes: 'Updated notes', // Optional: update notes
});

Offerings

List offerings

const offerings = await client.offerings.list({
  eventId: 'event_123', // Optional: filter by event
  providerId: 'provider_123', // Optional: filter by provider
});

Get an offering

const offering = await client.offerings.get('offering_123');

Create an offering

const offering = await client.offerings.create({
  name: '60-minute Therapy Session',
  description: 'One-on-one therapy session',
  price_cents: 15000, // $150.00
  duration_minutes: 60,
  timezone: 'America/New_York',
  attendee_mode: '1:1',
  providerIds: ['provider_123'], // Optional: associate with providers
  // Many more optional fields available for recurrence, scheduling windows, etc.
});

Simple Offering Creation (Recommended for most use cases)

For most clients, the helper methods below provide a simpler way to create offerings without dealing with complex recurrence patterns and availability windows.

Create a Simple Offering

Creates a basic 1:1 offering that uses provider availability schedules (no fixed times or recurrence):

const offering = await client.offerings.createSimple({
  name: 'Therapy Session',
  duration_minutes: 60,
  price_cents: 15000, // $150.00
  description: 'One-on-one therapy session',
  timezone: 'America/New_York', // Optional, defaults to organization timezone
  providerIds: ['provider_123'], // Optional: associate with providers
});

Create a Weekly Recurring Offering

Creates a weekly recurring offering with specific days and time slots:

const offering = await client.offerings.createRecurringWeekly({
  name: 'Weekly Therapy',
  duration_minutes: 60,
  days: ['monday', 'wednesday', 'friday'], // Can also use ['MO', 'WE', 'FR']
  timeSlots: [
    { start: '09:00', end: '12:00' },
    { start: '14:00', end: '17:00' }
  ],
  price_cents: 15000,
  description: 'Weekly therapy sessions',
  timezone: 'America/New_York',
  providerIds: ['provider_123'],
});

Create a Daily Recurring Offering

Creates a daily recurring offering with time slots:

const offering = await client.offerings.createRecurringDaily({
  name: 'Daily Consultation',
  duration_minutes: 30,
  timeSlots: [
    { start: '09:00', end: '12:00' },
    { start: '14:00', end: '17:00' }
  ],
  price_cents: 5000,
  description: 'Daily consultation slots',
  timezone: 'America/New_York',
  providerIds: ['provider_123'],
});

Update an offering

const updatedOffering = await client.offerings.update('offering_123', {
  price_cents: 12000, // Optional: update price
  duration_minutes: 90, // Optional: update duration
  // Many more optional fields available
});

Delete an offering

await client.offerings.delete('offering_123');

Create offering from simple endpoint

// Uses the simplified /offerings/simple endpoint with preset-based configuration
const offering = await client.offerings.createFromSimple({
  name: 'Therapy Session',
  duration_minutes: 60,
  price_cents: 15000,
  preset: 'simple_1on1', // 'simple_1on1' | 'simple_group' | 'recurring_weekly' | 'recurring_daily'
  provider_ids: ['provider_123'],
  // For recurring_weekly:
  // weekly_days: ['monday', 'wednesday'],
  // weekly_time_slots: [{ start: '09:00', end: '17:00' }],
  // For recurring_daily:
  // daily_time_slots: [{ start: '09:00', end: '17:00' }],
});

When to use helper methods vs. full API:

• Use createSimple() for basic offerings that rely on provider availability schedules
• Use createRecurringWeekly() or createRecurringDaily() for recurring offerings with fixed time slots
• Use createFromSimple() for preset-based configuration via the simplified endpoint
• Use create() directly when you need advanced features like custom recurrence intervals, monthly/yearly patterns, windowed modes, or other complex configurations

Customers

List customers

const customers = await client.customers.list({
  q: '[email protected]', // Optional: search by name/email/phone
  providerId: 'provider_123', // Optional: filter by provider
  page: 1,
  pageSize: 50,
});

Get a customer

const customer = await client.customers.get('customer_123');

Create a customer

const customer = await client.customers.create({
  name: 'John Doe',
  email: '[email protected]',
  phone: '+1234567890', // Optional
  userId: 'user_123', // Optional: link to internal user
});

Note: If a customer with the same email already exists, they will be merged/updated.

Update a customer

const updatedCustomer = await client.customers.update('customer_123', {
  name: 'John Smith', // Optional
  email: '[email protected]', // Optional
  phone: '+1987654321', // Optional
});

Delete a customer

await client.customers.delete('customer_123');

Get customer history

const history = await client.customers.getHistory('customer_123');
// Returns analytics, booking history, favorite providers, etc.

Providers

List providers

const providers = await client.providers.list({
  query: 'Dr. Smith', // Optional: search term
  page: 1,
  pageSize: 20,
});

Get a provider

const provider = await client.providers.get('provider_123');

Create a provider

const provider = await client.providers.create({
  name: 'Dr. Jane Smith',
  email: '[email protected]',
  phone: '+1234567890', // Optional
  bio: 'Licensed therapist with 10 years of experience', // Optional
  userId: 'user_123', // Optional: link to internal user
});

Update a provider

const updatedProvider = await client.providers.update('provider_123', {
  name: 'Dr. Jane Smith, PhD', // Optional
  email: '[email protected]', // Optional
  phone: '+1987654321', // Optional
  bio: 'Updated bio', // Optional
  minimum_advance_booking_minutes: 60, // Optional: minimum advance booking time in minutes
});

Delete a provider

await client.providers.delete('provider_123');

Google Calendar integration

// Get Google Calendar connection status
const status = await client.providers.getGoogleCalendarStatus('provider_123');
// Returns: { connected: boolean, email?: string, lastSync?: string }

// Sync Google Calendar
const syncResult = await client.providers.syncGoogleCalendar('provider_123');
// Returns: { success: boolean, syncedEvents?: number }

// Disconnect Google Calendar
await client.providers.disconnectGoogleCalendar('provider_123');

Calendar

Get calendar events

const events = await client.calendar.getEvents({
  providerId: 'provider_123', // Optional
  start: '2024-01-01T00:00:00Z', // Optional: start date
  end: '2024-01-31T23:59:59Z', // Optional: end date
});
// Returns both bookings and events combined

Analytics

Get revenue analytics

const revenue = await client.analytics.getRevenue({
  providerId: 'provider_123', // Optional
  startDate: '2024-01-01T00:00:00Z', // Optional
  endDate: '2024-01-31T23:59:59Z', // Optional
  groupBy: 'day', // Optional: 'day' | 'week' | 'month' | 'offering' | 'provider'
});

Get payouts

const payouts = await client.analytics.getPayouts({
  providerId: 'provider_123', // Optional
  startDate: '2024-01-01T00:00:00Z', // Optional
  endDate: '2024-01-31T23:59:59Z', // Optional
  customerId: 'customer_123', // Optional
});

Payments

Get payment intent

const paymentIntent = await client.payments.getIntent('pi_1234567890');
// Returns: { paymentIntentId, clientSecret, amount, status }

Update payment intent

const updatedIntent = await client.payments.updateIntent({
  paymentIntentId: 'pi_1234567890',
  tipAmountCents: 500, // Tip amount in cents
  bookingId: 'booking_123', // Optional: associate with booking
});

Organizations

Get organization details

const org = await client.orgs.get();
// Returns: { id, name, slug, timezone, clerk_org_id }

Get booking settings

const settings = await client.orgs.getBookingSettings();
// Returns booking configuration including safe period hours

Update booking settings

const updatedSettings = await client.orgs.updateBookingSettings({
  safe_period_hours: 24, // Minimum hours before bookings can be made
});

Availability

Get available slots

// Enhanced version with offeringId and limit support
const availability = await client.availability.getSlots({
  providerId: 'provider_123', // Optional if offeringId provided
  offeringId: 'offering_123', // Optional
  start: '2024-01-15T00:00:00Z',
  end: '2024-01-22T23:59:59Z',
  limit: 50, // Optional: max number of slots
});

// Or use the original format for backward compatibility
const availability2 = await client.availability.getSlots({
  providerId: 'provider_123',
  startDate: '2024-01-15T00:00:00Z',
  endDate: '2024-01-22T23:59:59Z',
});

Get availability schedules

const schedules = await client.availability.getSchedules({
  providerId: 'provider_123', // Optional
});

Check specific time availability

const isAvailable = await client.availability.check({
  providerId: 'provider_123',
  startTime: '2024-01-15T10:00:00Z',
  duration: 30, // minutes
});

Create an availability schedule

const schedule = await client.availability.createSchedule({
  providerId: 'provider_123',
  name: 'Business Hours',
  timezone: 'America/New_York',
  weekly_hours: {
    monday: [{ start: '09:00', end: '17:00' }],
    tuesday: [{ start: '09:00', end: '17:00' }],
    wednesday: [{ start: '09:00', end: '17:00' }],
    thursday: [{ start: '09:00', end: '17:00' }],
    friday: [{ start: '09:00', end: '17:00' }],
  },
  recurrence_preset: 'weekly',
  recurrence_end_mode: 'never', // or 'date' | 'count'
});

Get an availability schedule

const schedule = await client.availability.getSchedule('schedule_123');

Update an availability schedule

const updatedSchedule = await client.availability.updateSchedule('schedule_123', {
  name: 'Updated Schedule Name', // Optional
  timezone: 'America/Los_Angeles', // Optional
  weekly_hours: { /* updated hours */ }, // Optional
});

Delete an availability schedule

await client.availability.deleteSchedule('schedule_123');

Error Handling

The SDK throws typed errors for different scenarios:

import {
  AevumError,
  AevumAPIError,
  AevumAuthenticationError,
  AevumValidationError,
  AevumNotFoundError,
} from '@withaevum/sdk';

try {
  const booking = await client.bookings.get('invalid_id');
} catch (error) {
  if (error instanceof AevumNotFoundError) {
    console.log('Booking not found');
  } else if (error instanceof AevumAuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof AevumValidationError) {
    console.log('Validation error:', error.issues);
  } else if (error instanceof AevumAPIError) {
    console.log('API error:', error.message, error.status);
  }
}

TypeScript Support

The SDK is fully typed with TypeScript. All methods include type definitions for parameters and return values, providing autocomplete and type checking.

All types are exported for your convenience:

import type {
  Booking,
  Offering,
  Customer,
  Provider,
  CalendarEvent,
  RevenueResponse,
  PayoutsResponse,
  // ... and many more
} from '@withaevum/sdk';

Migration Guide (from Custom Client)

If you're migrating from a custom Aevum client implementation (like mendbloom's), here's how to update:

Before (Custom Client)

import { AevumClient } from '@/lib/aevum/client';

const client = new AevumClient(apiKey, orgId);
const offerings = await client.getOfferings({ eventId: 'event_123' });

After (SDK)

import { AevumClient } from '@withaevum/sdk';

const client = new AevumClient({ apiKey });
const offerings = await client.offerings.list({ eventId: 'event_123' });

Key Changes

1. Installation: npm install @withaevum/sdk
2. Initialization: No need to pass orgId - it's resolved automatically
3. Method Names: Use namespaced methods (e.g., client.offerings.list() instead of client.getOfferings())
4. Error Handling: Use SDK error classes instead of generic errors
5. Types: Import types from SDK instead of defining your own

Method Mapping

| Custom Client | SDK | |--------------|-----| | client.getOfferings() | client.offerings.list() | | client.getOffering(id) | client.offerings.get(id) | | client.createOffering() | client.offerings.create() | | client.getCustomers() | client.customers.list() | | client.getCustomer(id) | client.customers.get(id) | | client.createCustomer() | client.customers.create() | | client.getProviders() | client.providers.list() | | client.createProvider() | client.providers.create() | | client.getCalendarEvents() | client.calendar.getEvents() | | client.getRevenue() | client.analytics.getRevenue() | | client.getPayouts() | client.analytics.getPayouts() | | client.getAvailabilitySchedules() | client.availability.getSchedules() | | client.getAvailabilitySlots() | client.availability.getSlots() | | client.rescheduleBooking() | client.bookings.reschedule() |

Requirements

• Node.js 18+ or modern browser with fetch support
• Valid Aevum API key

License

ISC