@withaevum/sdk 0.0.1

package/README.md

@@ -0,0 +1,621 @@
+# @withaevum/sdk
+
+TypeScript SDK for the Aevum API - a comprehensive scheduling and booking management platform.
+
+## Installation
+
+```bash
+npm install @withaevum/sdk
+# or
+yarn add @withaevum/sdk
+# or
+pnpm add @withaevum/sdk
+```
+
+## Usage
+
+### Initialization
+
+```typescript
+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
+
+```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', // Note: API uses snake_case for these fields
+  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
+);
+```
+
+#### Confirm a booking
+
+```typescript
+const confirmedBooking = await client.bookings.confirm('booking_123', {
+  sendNotification: true, // Optional, default: false
+});
+```
+
+#### Update a booking
+
+```typescript
+const updatedBooking = await client.bookings.update('booking_123', {
+  status: 'confirmed', // Optional: update status
+  notes: 'Updated notes', // Optional: update notes
+});
+```
+
+### 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'],
+});
+```
+
+#### Update an offering
+
+```typescript
+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
+
+```typescript
+await client.offerings.delete('offering_123');
+```
+
+#### Create offering from simple endpoint
+
+```typescript
+// 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
+
+```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.
+
+#### Update a customer
+
+```typescript
+const updatedCustomer = await client.customers.update('customer_123', {
+  name: 'John Smith', // Optional
+  email: 'john.smith@example.com', // Optional
+  phone: '+1987654321', // Optional
+});
+```
+
+#### Delete a customer
+
+```typescript
+await client.customers.delete('customer_123');
+```
+
+#### 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
+});
+```
+
+#### Update a provider
+
+```typescript
+const updatedProvider = await client.providers.update('provider_123', {
+  name: 'Dr. Jane Smith, PhD', // Optional
+  email: 'jane.smith@example.com', // Optional
+  phone: '+1987654321', // Optional
+  bio: 'Updated bio', // Optional
+  minimum_advance_booking_minutes: 60, // Optional: minimum advance booking time in minutes
+});
+```
+
+#### Delete a provider
+
+```typescript
+await client.providers.delete('provider_123');
+```
+
+#### Google Calendar integration
+
+```typescript
+// 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
+
+```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
+});
+```
+
+### Payments
+
+#### Get payment intent
+
+```typescript
+const paymentIntent = await client.payments.getIntent('pi_1234567890');
+// Returns: { paymentIntentId, clientSecret, amount, status }
+```
+
+#### Update payment intent
+
+```typescript
+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
+
+```typescript
+const org = await client.orgs.get();
+// Returns: { id, name, slug, timezone, clerk_org_id }
+```
+
+#### Get booking settings
+
+```typescript
+const settings = await client.orgs.getBookingSettings();
+// Returns booking configuration including safe period hours
+```
+
+#### Update booking settings
+
+```typescript
+const updatedSettings = await client.orgs.updateBookingSettings({
+  safe_period_hours: 24, // Minimum hours before bookings can be made
+});
+```
+
+### 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
+});
+```
+
+#### Create an availability schedule
+
+```typescript
+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
+
+```typescript
+const schedule = await client.availability.getSchedule('schedule_123');
+```
+
+#### Update an availability schedule
+
+```typescript
+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
+
+```typescript
+await client.availability.deleteSchedule('schedule_123');
+```
+
+## Error Handling
+
+The SDK throws typed errors for different scenarios:
+
+```typescript
+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:
+
+```typescript
+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)
+
+```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 '@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

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 });
+    }
+}