@withaevum/sdk 1.0.0

package/README.md

@@ -0,0 +1,436 @@
+# @aevum/sdk
+
+TypeScript SDK for the Aevum API - a comprehensive scheduling and booking management platform.
+
+## Installation
+
+```bash
+npm install @aevum/sdk
+# or
+yarn add @aevum/sdk
+# or
+pnpm add @aevum/sdk
+```
+
+## Usage
+
+### Initialization
+
+```typescript
+import { AevumClient } from '@aevum/sdk';
+
+const client = new AevumClient({
+  apiKey: process.env.AEVUM_API_KEY,
+  // Optional: customize base URL (default: https://api.withaevum.com)
+  baseUrl: 'https://api.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
+
+```typescript
+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: 'customer@example.com',
+  // Optional:
+  // customerId: 'customer_789',
+  // customer: { name: 'John Doe', email: 'john@example.com', phone: '+1234567890' },
+  // price_cents: 5000,
+  // notes: 'Special request',
+  // status: 'pending',
+  // kind: 'standard',
+});
+```
+
+#### Get a booking
+
+```typescript
+const booking = await client.bookings.get('booking_123');
+```
+
+#### List bookings
+
+```typescript
+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
+
+```typescript
+const updatedBooking = await client.bookings.reschedule('booking_123', {
+  start_time: '2024-01-15T11:00:00Z',
+  end_time: '2024-01-15T11:30:00Z',
+  sendNotification: true, // Optional, default: false
+});
+```
+
+#### Cancel a booking
+
+```typescript
+const cancelledBooking = await client.bookings.cancel(
+  'booking_123',
+  'Customer requested cancellation', // Optional reason
+);
+```
+
+### Offerings
+
+#### List offerings
+
+```typescript
+const offerings = await client.offerings.list({
+  eventId: 'event_123', // Optional: filter by event
+  providerId: 'provider_123', // Optional: filter by provider
+});
+```
+
+#### Get an offering
+
+```typescript
+const offering = await client.offerings.get('offering_123');
+```
+
+#### Create an offering
+
+```typescript
+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):
+
+```typescript
+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:
+
+```typescript
+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:
+
+```typescript
+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'],
+});
+```
+
+**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 `create()` directly when you need advanced features like custom recurrence intervals, monthly/yearly patterns, windowed modes, or other complex configurations
+
+### Customers
+
+#### List customers
+
+```typescript
+const customers = await client.customers.list({
+  q: 'john@example.com', // Optional: search by name/email/phone
+  providerId: 'provider_123', // Optional: filter by provider
+  page: 1,
+  pageSize: 50,
+});
+```
+
+#### Get a customer
+
+```typescript
+const customer = await client.customers.get('customer_123');
+```
+
+#### Create a customer
+
+```typescript
+const customer = await client.customers.create({
+  name: 'John Doe',
+  email: 'john@example.com',
+  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.
+
+#### Get customer history
+
+```typescript
+const history = await client.customers.getHistory('customer_123');
+// Returns analytics, booking history, favorite providers, etc.
+```
+
+### Providers
+
+#### List providers
+
+```typescript
+const providers = await client.providers.list({
+  query: 'Dr. Smith', // Optional: search term
+  page: 1,
+  pageSize: 20,
+});
+```
+
+#### Get a provider
+
+```typescript
+const provider = await client.providers.get('provider_123');
+```
+
+#### Create a provider
+
+```typescript
+const provider = await client.providers.create({
+  name: 'Dr. Jane Smith',
+  email: 'jane@example.com',
+  phone: '+1234567890', // Optional
+  bio: 'Licensed therapist with 10 years of experience', // Optional
+  userId: 'user_123', // Optional: link to internal user
+});
+```
+
+### Calendar
+
+#### Get calendar events
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+});
+```
+
+### Availability
+
+#### Get available slots
+
+```typescript
+// 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
+
+```typescript
+const schedules = await client.availability.getSchedules({
+  providerId: 'provider_123', // Optional
+});
+```
+
+#### Check specific time availability
+
+```typescript
+const isAvailable = await client.availability.check({
+  providerId: 'provider_123',
+  startTime: '2024-01-15T10:00:00Z',
+  duration: 30, // minutes
+});
+```
+
+## Error Handling
+
+The SDK throws typed errors for different scenarios:
+
+```typescript
+import {
+  AevumError,
+  AevumAPIError,
+  AevumAuthenticationError,
+  AevumValidationError,
+  AevumNotFoundError,
+} from '@aevum/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:
+
+```typescript
+import type {
+  Booking,
+  Offering,
+  Customer,
+  Provider,
+  CalendarEvent,
+  RevenueResponse,
+  PayoutsResponse,
+  // ... and many more
+} from '@aevum/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)
+
+```typescript
+import { AevumClient } from '@/lib/aevum/client';
+
+const client = new AevumClient(apiKey, orgId);
+const offerings = await client.getOfferings({ eventId: 'event_123' });
+```
+
+### After (SDK)
+
+```typescript
+import { AevumClient } from '@aevum/sdk';
+
+const client = new AevumClient({ apiKey });
+const offerings = await client.offerings.list({ eventId: 'event_123' });
+```
+
+### Key Changes
+
+1. **Installation**: `npm install @aevum/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

package/dist/analytics.d.ts

@@ -0,0 +1,17 @@
+import { AevumClient } from './client';
+import type { GetRevenueParams, RevenueResponse, GetPayoutsParams, PayoutsResponse } from './types';
+/**
+ * Analytics API methods
+ */
+export declare class AnalyticsAPI {
+    private client;
+    constructor(client: AevumClient);
+    /**
+     * Get revenue analytics
+     */
+    getRevenue(params?: GetRevenueParams): Promise<RevenueResponse>;
+    /**
+     * Get payouts (revenue from confirmed bookings)
+     */
+    getPayouts(params?: GetPayoutsParams): Promise<PayoutsResponse>;
+}

package/dist/analytics.js

@@ -0,0 +1,46 @@
+/**
+ * Analytics API methods
+ */
+export class AnalyticsAPI {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Get revenue analytics
+     */
+    async getRevenue(params) {
+        const query = {};
+        if (params?.providerId) {
+            query.providerId = params.providerId;
+        }
+        if (params?.startDate) {
+            query.startDate = params.startDate;
+        }
+        if (params?.endDate) {
+            query.endDate = params.endDate;
+        }
+        if (params?.groupBy) {
+            query.groupBy = params.groupBy;
+        }
+        return this.client.request('GET', '/api/v1/orgs/{orgId}/analytics/revenue', { query });
+    }
+    /**
+     * Get payouts (revenue from confirmed bookings)
+     */
+    async getPayouts(params) {
+        const query = {};
+        if (params?.providerId) {
+            query.providerId = params.providerId;
+        }
+        if (params?.startDate) {
+            query.startDate = params.startDate;
+        }
+        if (params?.endDate) {
+            query.endDate = params.endDate;
+        }
+        if (params?.customerId) {
+            query.customerId = params.customerId;
+        }
+        return this.client.request('GET', '/api/v1/orgs/{orgId}/payouts', { query });
+    }
+}

package/dist/availability.d.ts

@@ -0,0 +1,23 @@
+import { AevumClient } from './client';
+import type { GetSlotsParams, GetSlotsResponse, CheckAvailabilityParams, CheckAvailabilityResponse, GetAvailabilitySchedulesParams, AvailabilitySchedule, GetAvailabilitySlotsParams } from './types';
+/**
+ * Availability API methods
+ */
+export declare class AvailabilityAPI {
+    private client;
+    constructor(client: AevumClient);
+    /**
+     * Get available time slots for a provider within a date range
+     * Enhanced version that supports offeringId and limit
+     */
+    getSlots(params: GetSlotsParams | GetAvailabilitySlotsParams): Promise<GetSlotsResponse>;
+    /**
+     * Get availability schedules
+     */
+    getSchedules(params?: GetAvailabilitySchedulesParams): Promise<AvailabilitySchedule[]>;
+    /**
+     * Check if a specific time slot is available
+     * This is a client-side implementation that uses getSlots()
+     */
+    check(params: CheckAvailabilityParams): Promise<CheckAvailabilityResponse>;
+}

package/dist/availability.js

@@ -0,0 +1,114 @@
+/**
+ * Availability API methods
+ */
+export class AvailabilityAPI {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Get available time slots for a provider within a date range
+     * Enhanced version that supports offeringId and limit
+     */
+    async getSlots(params) {
+        const query = {};
+        // Support both old and new parameter formats
+        if ('providerId' in params && params.providerId) {
+            query.providerId = params.providerId;
+        }
+        if ('offeringId' in params && params.offeringId) {
+            query.offeringId = params.offeringId;
+        }
+        if ('start' in params && params.start) {
+            query.start = params.start;
+        }
+        else if ('startDate' in params && params.startDate) {
+            query.start = params.startDate;
+        }
+        if ('end' in params && params.end) {
+            query.end = params.end;
+        }
+        else if ('endDate' in params && params.endDate) {
+            query.end = params.endDate;
+        }
+        if ('limit' in params && params.limit !== undefined) {
+            query.limit = params.limit;
+        }
+        // For backward compatibility with GetSlotsParams
+        if ('startDate' in params && 'endDate' in params) {
+            if (!params.startDate || !params.endDate) {
+                throw new Error('startDate and endDate are required');
+            }
+        }
+        else if (!query.start || !query.end) {
+            throw new Error('start/startDate and end/endDate are required');
+        }
+        try {
+            return await this.client.request('GET', '/api/v1/orgs/{orgId}/availability/slots', { query });
+        }
+        catch (error) {
+            // Handle 404 gracefully - endpoint might not exist yet
+            if (error?.status === 404 || error?.message?.includes('404')) {
+                console.warn('Availability slots endpoint not found, returning empty slots');
+                return { slots: [] };
+            }
+            throw error;
+        }
+    }
+    /**
+     * Get availability schedules
+     */
+    async getSchedules(params) {
+        const query = {};
+        if (params?.providerId) {
+            query.providerId = params.providerId;
+        }
+        try {
+            const response = await this.client.request('GET', '/api/v1/orgs/{orgId}/availability/schedules', { query });
+            return response || [];
+        }
+        catch (error) {
+            // Handle 404 gracefully - endpoint might not exist yet
+            if (error?.status === 404 || error?.message?.includes('404')) {
+                console.warn('Availability schedules endpoint not found, returning empty array');
+                return [];
+            }
+            throw error;
+        }
+    }
+    /**
+     * Check if a specific time slot is available
+     * This is a client-side implementation that uses getSlots()
+     */
+    async check(params) {
+        const { providerId, startTime, duration } = params;
+        // Parse start time
+        const start = new Date(startTime);
+        if (isNaN(start.getTime())) {
+            throw new Error('Invalid startTime format. Expected ISO 8601 datetime with timezone');
+        }
+        // Calculate end time
+        const end = new Date(start.getTime() + duration * 60 * 1000);
+        // Get slots for a window around the requested time (1 day before and after)
+        const windowStart = new Date(start.getTime() - 24 * 60 * 60 * 1000);
+        const windowEnd = new Date(end.getTime() + 24 * 60 * 60 * 1000);
+        // Format as ISO strings with timezone
+        const startDate = windowStart.toISOString();
+        const endDate = windowEnd.toISOString();
+        // Get available slots
+        const { slots } = await this.getSlots({
+            providerId,
+            startDate,
+            endDate,
+        });
+        // Check if requested time falls within any available slot
+        const requestedStart = start.getTime();
+        const requestedEnd = end.getTime();
+        const isAvailable = slots.some((slot) => {
+            const slotStart = new Date(slot.start_time_utc).getTime();
+            const slotEnd = new Date(slot.end_time_utc).getTime();
+            // Check if requested time is completely within the slot
+            return requestedStart >= slotStart && requestedEnd <= slotEnd;
+        });
+        return { available: isAvailable };
+    }
+}

package/dist/bookings.d.ts

@@ -0,0 +1,29 @@
+import { AevumClient } from './client';
+import type { Booking, CreateBookingParams, ListBookingsParams, ListBookingsResponse, RescheduleBookingParams } from './types';
+/**
+ * Bookings API methods
+ */
+export declare class BookingsAPI {
+    private client;
+    constructor(client: AevumClient);
+    /**
+     * Create a new booking
+     */
+    create(params: CreateBookingParams): Promise<Booking>;
+    /**
+     * Get a booking by ID
+     */
+    get(bookingId: string): Promise<Booking>;
+    /**
+     * List bookings with optional filters
+     */
+    list(params?: ListBookingsParams): Promise<ListBookingsResponse>;
+    /**
+     * Cancel a booking
+     */
+    cancel(bookingId: string, reason?: string): Promise<Booking>;
+    /**
+     * Reschedule a booking
+     */
+    reschedule(bookingId: string, params: RescheduleBookingParams): Promise<Booking>;
+}