recal-sdk 0.1.1 → 0.2.1

package/README.md

@@ -10,8 +10,8 @@ A powerful, type-safe SDK for interacting with the Recal calendar API. Build sop
 
 - **Multi-Provider Support**: Seamlessly work with Google Calendar and Microsoft Outlook
 - **Type Safety**: Full TypeScript support with runtime validation
-- **Rich Calendar Operations**: Events, free/busy queries, scheduling, and more
-- **Organization Management**: Handle teams and multi-user calendar scenarios
+- **Rich Calendar Operations**: Events, busy queries, scheduling, and more
+- **Organization Management**: Handle organizations and users calendars
 - **OAuth Integration**: Built-in OAuth flow support for calendar connections
 - **Error Handling**: Comprehensive error types for robust applications
 - **Modern Architecture**: Clean, testable service-based design
@@ -36,31 +36,12 @@ bun add recal-sdk
 ```typescript
 import { RecalClient } from 'recal-sdk'
 
-// Initialize the client
-const recal = new RecalClient({
-    token: 'recal_your_api_token', // or use RECAL_TOKEN env variable
-    url: 'https://api.recal.dev'   // optional, defaults to production
-})
-```
-
-### Authentication
-
-The SDK requires a Recal API token. You can provide it in three ways:
-
-1. **Direct in constructor** (recommended for server-side apps):
-```typescript
-const recal = new RecalClient({ token: 'recal_your_token' })
-```
+// Initialize the client with token from .env file (RECAL_TOKEN)
+const recal = new RecalClient()
 
-2. **Environment variable**:
-```bash
-export RECAL_TOKEN="recal_your_token"
-```
-
-3. **Function (for dynamic tokens)**:
-```typescript
+// Or manually provide the token
 const recal = new RecalClient({ 
-    token: () => getTokenFromSecureStore() 
+    token: "recal_xyz"
 })
 ```
 
@@ -72,100 +53,169 @@ const recal = new RecalClient({
 
 The SDK is organized into logical service modules:
 
-- **`calendar`** - Event management and free/busy queries
+- **`calendar`** - Event management and busy queries
 - **`scheduling`** - Availability and booking management
 - **`users`** - User profile and settings
 - **`organizations`** - Team and organization management
 - **`oauth`** - Calendar provider authentication
 
-### Providers
-
-Recal supports two calendar providers:
-- `google` - Google Calendar
-- `microsoft` - Microsoft Outlook/Office 365
-
 ### Time Zones
 
-All date/time operations support timezone specification via the `timeZone` parameter or `x-timezone` header.
+All date/time operations support timezone specification via the `timeZone` parameter.
 
 ## API Reference
 
+> TypeScript note
+>
+> - Use the exported `Provider` enum for provider arguments.
+> - Date/time fields in responses are parsed into `Date` objects at runtime.
+>
+> ```typescript
+> import { Provider } from 'recal-sdk'
+> ```
+
 ### Calendar Service
 
-#### Get Free/Busy Information
+#### Get Busy Information
 
 ```typescript
-// Get user's availability
-const freeBusy = await recal.calendar.getFreeBusy(
+// Get user's availability (simplest form)
+const busy = await recal.calendar.getBusy(
+    'user_id',
+    new Date('2024-01-01'),
+    new Date('2024-01-07')
+)
+
+// Or with optional filters
+const busyFiltered = await recal.calendar.getBusy(
     'user_id',
     new Date('2024-01-01'),
     new Date('2024-01-07'),
-    'google',  // optional: filter by provider
-    'America/New_York'  // optional: timezone
+    {
+        provider: 'google',  // optional: filter by provider
+        timeZone: 'America/New_York',  // optional: timezone
+    }
 )
 ```
 
 #### List Events
 
 ```typescript
-// Get all events in a date range
+// Get all events in a date range (simplest form)
 const events = await recal.calendar.getEvents(
+    'user_id',
+    new Date('2024-01-01'),
+    new Date('2024-01-31')
+)
+
+// Or with optional filters
+const eventsFiltered = await recal.calendar.getEvents(
     'user_id',
     new Date('2024-01-01'),
     new Date('2024-01-31'),
-    ['google', 'microsoft'],  // optional: multiple providers
-    'Europe/London'
+    {
+        provider: 'google',  // optional: filter by provider
+        timeZone: 'Europe/London'  // optional: timezone
+    }
 )
 ```
 
 #### Create Event
 
 ```typescript
-// Create a new event
-const event = await recal.calendar.createEvent(
-    'user_id',
-    'google',
-    'calendar_id',
-    {
-        summary: 'Team Meeting',
+// Create a new event (without optional timezone)
+const event = await recal.calendar.createEvent({
+    userId: 'user_id',
+    provider: 'google',
+    calendarId: 'calendar_id',
+    event: {
+        subject: 'Team Meeting',
+        description: 'Weekly sync',
+        start: new Date('2024-01-15T10:00:00Z'),
+        end: new Date('2024-01-15T11:00:00Z'),
+        attendees: [
+            { email: 'colleague@company.com' }
+        ]
+    }
+})
+
+// Or with timezone option
+const eventWithTZ = await recal.calendar.createEvent({
+    userId: 'user_id',
+    provider: 'google',
+    calendarId: 'calendar_id',
+    event: {
+        subject: 'Team Meeting',
         description: 'Weekly sync',
-        start: { dateTime: '2024-01-15T10:00:00Z' },
-        end: { dateTime: '2024-01-15T11:00:00Z' },
+        start: new Date('2024-01-15T10:00:00Z'),
+        end: new Date('2024-01-15T11:00:00Z'),
         attendees: [
             { email: 'colleague@company.com' }
         ]
     },
-    'America/Los_Angeles'
-)
+    options: { timeZone: 'Europe/Berlin' }  // optional
+})
+```
+#### Get Event
+
+```typescript
+// Get an existing event
+const event = await recal.calendar.getEvent({
+    userId: 'user_id',
+    provider: 'google',
+    calendarId: 'calendar_id',
+    eventId: 'event_id',
+    options: { timeZone: 'Europe/Berlin' }  // optional
+})
 ```
 
 #### Update Event
 
 ```typescript
-// Update an existing event
-const updated = await recal.calendar.updateEvent(
-    'user_id',
-    'google',
-    'calendar_id',
-    'event_id',
-    {
-        summary: 'Updated Meeting Title',
-        start: { dateTime: '2024-01-15T14:00:00Z' },
-        end: { dateTime: '2024-01-15T15:00:00Z' }
+// Update an existing event (simplest form)
+const updated = await recal.calendar.updateEvent({
+    userId: 'user_id',
+    provider: 'google',
+    calendarId: 'calendar_id',
+    eventId: 'event_id',
+    event: {
+        subject: 'Updated Meeting Title',
+        start: new Date('2024-01-15T14:00:00Z'),
+        end: new Date('2024-01-15T15:00:00Z')
     }
-)
+})
+```
+
+```typescript
+// or with more options
+const updated = await recal.calendar.updateEvent({
+    userId: 'user_id',
+    provider: 'google',
+    calendarId: 'calendar_id',
+    eventId: 'event_id',
+    event: {
+        subject: 'Updated Meeting title',
+        description: 'Updated description',
+        start: new Date('2024-01-15T11:00:00Z'),
+        end: new Date('2024-01-15T12:00:00Z'),
+        attendees: [
+            { email: 'colleague@company.com' }
+        ]
+    },
+    options: { timeZone: 'Europe/Berlin' }  // optional
+})
 ```
 
 #### Delete Event
 
 ```typescript
 // Delete an event
-await recal.calendar.deleteEvent(
-    'user_id',
-    'google',
-    'calendar_id',
-    'event_id'
-)
+await recal.calendar.deleteEvent({
+    userId: 'user_id',
+    provider: 'google',
+    calendarId: 'calendar_id',
+    eventId: 'event_id'
+})
 ```
 
 #### Cross-Calendar Operations (Meta Events)
@@ -173,22 +223,41 @@ await recal.calendar.deleteEvent(
 Meta events allow you to work with events across multiple calendar providers:
 
 ```typescript
-// Create event across all connected calendars
+// Create event across all connected calendars (default behavior)
 const metaEvent = await recal.calendar.createEventByMetaId(
     'user_id',
     {
-        summary: 'Cross-platform meeting',
-        start: { dateTime: '2024-01-20T15:00:00Z' },
-        end: { dateTime: '2024-01-20T16:00:00Z' }
+        subject: 'Cross-platform meeting',
+        start: new Date('2024-01-20T15:00:00Z'),
+        end: new Date('2024-01-20T16:00:00Z')
+    }
+)
+
+// Or specify which providers and timezone to use
+const metaEventSpecific = await recal.calendar.createEventByMetaId(
+    'user_id',
+    {
+        subject: 'Cross-platform meeting',
+        start: new Date('2024-01-20T15:00:00Z'),
+        end: new Date('2024-01-20T16:00:00Z')
     },
-    ['google', 'microsoft']  // Create on both providers
+    { 
+        provider: ['google', 'microsoft'], // Create on specific providers
+        timeZone: 'Europe/Berlin' // optional
+    }  
+)
+
+// Get event across all connected calendars (default behavior)
+const metaEventGet = await recal.calendar.getEventByMetaId(
+    'user_id',
+    metaEvent.metaId
 )
 
 // Update across all calendars using meta ID
 await recal.calendar.updateEventByMetaId(
     'user_id',
     metaEvent.metaId,
-    { summary: 'Updated title' }
+    { subject: 'Updated title' }
 )
 
 // Delete from all calendars
@@ -200,136 +269,318 @@ await recal.calendar.deleteEventByMetaId(
 
 ### Scheduling Service
 
-#### Get Availability
+#### Get User Availability (Basic)
 
 ```typescript
-// Find available time slots
-const availability = await recal.scheduling.getAvailability(
+// Find available time slots (minimal config)
+const availability = await recal.scheduling.userSchedulingBasic(
+    'user_id',
+    new Date('2024-01-15'),
+    new Date('2024-01-20'),
+    {
+        slotDuration: 30  // Only required: slot duration in minutes
+    }
+)
+
+// Or with more options
+const availabilityDetailed = await recal.scheduling.userSchedulingBasic(
     'user_id',
     new Date('2024-01-15'),
     new Date('2024-01-20'),
     {
-        duration: 30,  // 30-minute slots
-        interval: 15,  // 15-minute intervals
-        startTime: '09:00',
-        endTime: '17:00'
+        slotDuration: 30,  // Duration of each slot in minutes
+        padding: 0,  // Padding between slots
+        earliestTimeEachDay: '09:00',  // Format: HH:mm
+        latestTimeEachDay: '17:00',  // Format: HH:mm
+        provider: 'google',  // optional: filter by provider
+        timeZone: 'America/New_York'  // optional
     }
 )
 ```
 
-#### Book Time Slot
+#### Get User Availability (Advanced)
 
 ```typescript
-// Book an available slot
-const booking = await recal.scheduling.bookSlot(
+// Find available time slots with custom schedules
+const schedules = [
+    {
+        days: ['monday'],  // Monday
+        start: '09:00',
+        end: '17:00'
+    },
+    // ... more schedule rules
+]
+
+// Minimal config
+const availability = await recal.scheduling.userSchedulingAdvanced(
     'user_id',
+    schedules,
+    new Date('2024-01-15'),
+    new Date('2024-01-20'),
+    { slotDuration: 30 }  // Only required option
+)
+
+// Or with more options
+const availabilityDetailed = await recal.scheduling.userSchedulingAdvanced(
+    'user_id',
+    schedules,
+    new Date('2024-01-15'),
+    new Date('2024-01-20'),
+    {
+        slotDuration: 30,
+        padding: 15,
+        provider: 'google',  // optional
+        timeZone: 'America/New_York'  // optional
+    }
+)
+```
+
+#### Get Organization-Wide Availability
+
+```typescript
+// Find organization-wide available time slots (minimal)
+const orgAvailability = await recal.scheduling.getOrgWideAvailability(
+    'org-slug',
+    new Date('2024-01-15'),
+    new Date('2024-01-20'),
+    { slotDuration: 60 }  // Only required option
+)
+
+// Or with constraints
+const orgAvailabilityConstrained = await recal.scheduling.getOrgWideAvailability(
+    'org-slug',
+    new Date('2024-01-15'),
+    new Date('2024-01-20'),
     {
-        start: '2024-01-15T10:00:00Z',
-        end: '2024-01-15T10:30:00Z',
-        title: 'Consultation',
-        attendees: ['client@example.com']
+        slotDuration: 60,
+        padding: 0,
+        earliestTimeEachDay: '09:00',
+        latestTimeEachDay: '17:00',
+        provider: ['google', 'microsoft'],  // optional
+        timeZone: 'America/New_York'  // optional
     }
 )
 ```
 
 ### Users Service
 
-#### Get User Profile
+#### Get User
 
 ```typescript
-// Get user information
-const user = await recal.users.getUser('user_id')
-console.log(user.email, user.name)
+// Get user information (basic)
+const user = await recal.users.get('user_id', {})
+
+// Or with additional data
+const userWithDetails = await recal.users.get('user_id', {
+    includeOrgs: true,  // Include organizations
+    includeOAuth: true  // Include OAuth connections
+})
+console.log(user.id)
 ```
 
-#### List User's Calendars
+#### List All Users
 
 ```typescript
-// Get all connected calendars
-const calendars = await recal.users.getCalendars('user_id', {
-    includeOrganization: true
-})
+// Get all users
+const users = await recal.users.listAll()
 ```
 
-#### Update User Settings
+#### Create User
 
 ```typescript
-// Update user preferences
-await recal.users.updateSettings('user_id', {
-    defaultCalendarId: 'calendar_123',
-    timezone: 'America/New_York',
-    workingHours: {
-        start: '09:00',
-        end: '17:00'
-    }
+// Create a new user (without organizations)
+const user = await recal.users.create('user_id')
+
+// Or with organization memberships
+const userWithOrgs = await recal.users.create(
+    'user_id',
+    ['org-slug-1', 'org-slug-2']  // optional: organization slugs
+)
+```
+
+#### Update User
+
+```typescript
+// Update user ID
+const updatedUser = await recal.users.update('old_user_id', {
+    id: 'new_user_id'
 })
 ```
 
+#### Delete User
+
+```typescript
+// Delete a user
+const deletedUser = await recal.users.delete('user_id')
+```
+
 ### Organizations Service
 
 #### Get Organization
 
 ```typescript
 // Get organization by slug
-const org = await recal.organizations.getOrganization('acme-corp', {
-    includeUsers: true,
-    includeSettings: true
+const org = await recal.organizations.get('acme-corp')
+```
+
+#### List All Organizations
+
+```typescript
+// Get all organizations
+const orgs = await recal.organizations.listAll()
+
+// Get organizations for a specific user
+const userOrgs = await recal.organizations.listAllFromUser('user_id')
+```
+
+#### Create Organization
+
+```typescript
+// Create a new organization
+const org = await recal.organizations.create(
+    'acme-corp',  // slug
+    'Acme Corporation'  // name
+)
+```
+
+#### Update Organization
+
+```typescript
+// Update organization
+const updated = await recal.organizations.update('acme-corp', {
+    slug: 'new-slug',
+    name: 'New Name'
 })
 ```
 
-#### List Organization Members
+#### Manage Members
 
 ```typescript
 // Get all members
-const members = await recal.organizations.getMembers('org_id')
+const members = await recal.organizations.getMembers('acme-corp')
+
+// Add members
+await recal.organizations.addMembers(
+    'acme-corp',
+    ['user_id_1', 'user_id_2']
+)
+
+// Remove members
+await recal.organizations.removeMembers(
+    'acme-corp',
+    ['user_id_1', 'user_id_2']
+)
 ```
 
-#### Organization-Wide Free/Busy
+#### Organization-Wide Busy
 
 ```typescript
-// Get team availability
-const teamBusy = await recal.calendar.getOrgWideFreeBusy(
+// Get team availability (simplest form)
+const teamBusy = await recal.calendar.getOrgWideBusy(
+    'acme-corp',
+    new Date('2024-01-15'),
+    new Date('2024-01-20'),
+    true  // primaryOnly: only check primary calendars
+)
+
+// Or with optional filters
+const teamBusyFiltered = await recal.calendar.getOrgWideBusy(
     'acme-corp',
     new Date('2024-01-15'),
     new Date('2024-01-20'),
     true,  // primaryOnly: only check primary calendars
-    'google'
+    {
+        provider: 'google',  // optional: filter by provider
+        timeZone: 'America/New_York'  // optional
+    }
 )
 ```
 
 ### OAuth Service
 
-#### Generate OAuth URL
+#### Get OAuth Link
 
 ```typescript
-// Create OAuth authorization URL
-const authUrl = await recal.oauth.generateAuthUrl({
-    provider: 'google',
-    userId: 'user_id',
-    redirectUri: 'https://app.example.com/callback',
-    scopes: ['calendar.events', 'calendar.readonly']
-})
+// Get OAuth authorization URL (with defaults)
+const link = await recal.oauth.getLink(
+    'user_id',
+    'google'
+)
+
+// Or with custom options
+const linkWithOptions = await recal.oauth.getLink(
+    'user_id',
+    'google',
+    {
+        scope: 'edit',  // 'edit' or 'free-busy' (for OAuth scopes)
+        accessType: 'offline',  // 'offline' or 'online'
+        redirectUrl: 'https://app.example.com/callback'  // optional
+    }
+)
+console.log(link.url)  // Use this URL to redirect user
 ```
 
-#### Exchange OAuth Code
+#### Get Multiple OAuth Links
 
 ```typescript
-// Exchange authorization code for tokens
-const tokens = await recal.oauth.exchangeCode({
-    provider: 'google',
-    code: 'auth_code_from_callback',
-    redirectUri: 'https://app.example.com/callback'
-})
+// Get OAuth URLs for all providers (simplest)
+const links = await recal.oauth.getBulkLinks('user_id')
+
+// Or with specific providers and options
+const linksFiltered = await recal.oauth.getBulkLinks(
+    'user_id',
+    {
+        provider: ['google', 'microsoft'],
+        scope: 'edit',
+        accessType: 'offline'
+    }
+)
 ```
 
-#### Refresh OAuth Token
+#### Manage OAuth Connections
 
 ```typescript
-// Refresh expired token
-const newTokens = await recal.oauth.refreshToken({
-    provider: 'google',
-    refreshToken: 'stored_refresh_token'
-})
+// Get all OAuth connections for a user
+const connections = await recal.oauth.getAllConnections(
+    'user_id',
+    true  // redacted (default: true)
+)
+
+// Get specific provider connection
+const googleConnection = await recal.oauth.getConnection(
+    'user_id',
+    'google',
+    false  // redacted
+)
+
+// Set OAuth tokens manually
+const connection = await recal.oauth.setConnection(
+    'user_id',
+    'google',
+    {
+        accessToken: 'access_token',
+        refreshToken: 'refresh_token',  // optional
+        scope: ['calendar.events', 'calendar.readonly'],
+        expiresAt: new Date('2024-12-31'),  // optional
+        email: 'user@example.com'  // optional
+    }
+)
+
+// Disconnect a provider
+await recal.oauth.disconnect('user_id', 'google')
+```
+
+#### Verify OAuth Callback
+
+```typescript
+// Verify OAuth code from callback
+const result = await recal.oauth.verify(
+    'google',
+    'auth_code_from_callback',
+    'edit',  // 'edit' or 'free-busy' - single scope, not array
+    'state_parameter',
+    'https://app.example.com/callback'  // optional
+)
 ```
 
 ## Advanced Usage
@@ -347,12 +598,12 @@ import {
 } from 'recal-sdk'
 
 try {
-    const event = await recal.calendar.getEvent(
-        'user_id', 
-        'google', 
-        'calendar_id', 
-        'event_id'
-    )
+    const event = await recal.calendar.getEvent({
+        userId: 'user_id',
+        provider: 'google',
+        calendarId: 'calendar_id',
+        eventId: 'event_id'
+    })
 } catch (error) {
     if (error instanceof UserNotFoundError) {
         console.log('User does not exist:', error.userId)
@@ -367,7 +618,7 @@ try {
 ### Batch Operations
 
 ```typescript
-// Process multiple users' calendars
+// Process multiple users' calendars (simplest form)
 const userIds = ['user1', 'user2', 'user3']
 const allEvents = await Promise.all(
     userIds.map(userId => 
@@ -383,36 +634,41 @@ const allEvents = await Promise.all(
 ### Working with Multiple Providers
 
 ```typescript
-// Aggregate availability across providers
+// Get all busy data (without filtering)
+const startDate = new Date('2024-01-01')
+const endDate = new Date('2024-01-31')
+
+const allBusy = await recal.calendar.getBusy(
+    'user_id',
+    startDate,
+    endDate
+)
+
+// Or aggregate by specific providers
 const providers: Provider[] = ['google', 'microsoft']
 const busyTimes = await Promise.all(
-    providers.map(provider =>
-        recal.calendar.getFreeBusy(
+    providers.map(provider => 
+        recal.calendar.getBusy(
             'user_id',
             startDate,
             endDate,
-            provider
+            { provider }  // filter by specific provider
         )
     )
 )
 
-// Merge busy periods
-const merged = mergeBusyPeriods(busyTimes)
+// Process the busy times as needed for your application
+// Each element is Busy = TimeRange[]; flatten into a single array of TimeRange
+const allBusyPeriods = busyTimes.flat()
 ```
 
 ### Custom Request Configuration
 
 ```typescript
-// Use custom headers or timeout
+// Use custom base URL
 const recal = new RecalClient({
     token: 'recal_token',
-    url: 'https://api.recal.dev',
-    requestConfig: {
-        timeout: 30000,  // 30 seconds
-        headers: {
-            'X-Custom-Header': 'value'
-        }
-    }
+    url: 'https://api.recal.dev'  // optional, this is the default
 })
 ```
 
@@ -422,34 +678,42 @@ const recal = new RecalClient({
 
 ```typescript
 // 1. Check availability
-const slots = await recal.scheduling.getAvailability(
+const availability = await recal.scheduling.userSchedulingBasic(
     'consultant_id',
     new Date(),
     new Date(Date.now() + 7 * 24 * 60 * 60 * 1000), // Next 7 days
     {
-        duration: 60,
-        interval: 30,
-        startTime: '09:00',
-        endTime: '17:00'
+        slotDuration: 60,  // 60-minute slots
+        padding: 15,  // 15-minute padding between slots
+        earliestTimeEachDay: '09:00',
+        latestTimeEachDay: '17:00',
+        timeZone: 'America/New_York'
     }
 )
 
 // 2. Display available slots to user
-const availableSlots = slots.filter(slot => !slot.busy)
+const availableSlots = availability.availableSlots  // Already filtered for availability
 
-// 3. Book selected slot
-const booking = await recal.scheduling.bookSlot(
-    'consultant_id',
-    {
+// 3. User selects a slot and provides their information
+const selectedSlot = availableSlots[0]  // Example: first available slot
+const clientName = 'John Doe'
+const clientEmail = 'john@example.com'
+
+// 4. Create an event for the selected slot (using calendar service)
+const booking = await recal.calendar.createEvent({
+    userId: 'consultant_id',
+    provider: 'google',
+    calendarId: 'primary',
+    event: {
+        subject: 'Consultation with ' + clientName,
+        description: 'Initial consultation',
         start: selectedSlot.start,
         end: selectedSlot.end,
-        title: 'Consultation with ' + clientName,
-        description: 'Initial consultation',
-        attendees: [clientEmail]
+        attendees: [{ email: clientEmail }]
     }
-)
+})
 
-// 4. Send confirmation
+// 5. Send confirmation
 console.log('Booking confirmed:', booking.id)
 ```
 
@@ -458,29 +722,36 @@ console.log('Booking confirmed:', booking.id)
 ```typescript
 // Sync events between providers
 async function syncCalendars(userId: string) {
-    // Get events from Google
+    // Get all events from all providers
+    const allEvents = await recal.calendar.getEvents(
+        userId,
+        new Date(),
+        new Date(Date.now() + 30 * 24 * 60 * 60 * 1000)
+    )
+    
+    // Or get events from Google only
     const googleEvents = await recal.calendar.getEvents(
         userId,
         new Date(),
         new Date(Date.now() + 30 * 24 * 60 * 60 * 1000),
-        'google'
+        { provider: 'google' }
     )
     
     // Copy to Microsoft calendar
     for (const event of googleEvents) {
         if (!event.metaId) { // Not already synced
-            await recal.calendar.createEvent(
+            await recal.calendar.createEvent({
                 userId,
-                'microsoft',
-                'primary',
-                {
-                    summary: event.summary,
+                provider: 'microsoft',
+                calendarId: 'primary',
+                event: {
+                    subject: event.subject,
                     description: event.description,
                     start: event.start,
                     end: event.end,
                     attendees: event.attendees
                 }
-            )
+            })
         }
     }
 }
@@ -496,32 +767,40 @@ async function findTeamSlot(
     startDate: Date,
     endDate: Date
 ) {
-    // Get organization members
-    const org = await recal.organizations.getOrganization(orgSlug, {
-        includeUsers: true
-    })
-    
-    // Get everyone's busy times
-    const busyTimes = await recal.calendar.getOrgWideFreeBusy(
+    // Option 1: Get raw busy times for manual processing
+    const busyTimes = await recal.calendar.getOrgWideBusy(
         orgSlug,
         startDate,
         endDate,
-        true // Only check primary calendars
+        true  // Only check primary calendars
     )
+    // Process busyTimes array to find gaps for your needs
     
-    // Find gaps where everyone is free
-    const freeSlots = findFreeSlots(busyTimes, duration)
+    // Option 2: Use the scheduling service (recommended)
+    const availability = await recal.scheduling.getOrgWideAvailability(
+        orgSlug,
+        startDate,
+        endDate,
+        {
+            slotDuration: duration,
+            padding: 0,
+            earliestTimeEachDay: '09:00',
+            latestTimeEachDay: '17:00'
+        }
+    )
     
-    return freeSlots
+    // Returns ready-to-use available time slots
+    return availability.availableSlots
 }
 ```
 
-## Development
+## SDK Development
 
 ### Prerequisites
 
-- Node.js 18+ or Bun 1.0+
+- Node.js 18+ or Bun 1.0+, or any other JavaScript runtime
 - TypeScript 5.0+
+- Biome 2.1.2 (for contributing)
 
 ### Setup
 
@@ -553,17 +832,27 @@ src/
 │   └── oauth.service.ts
 ├── entities/             # Domain models
 │   ├── user.ts
-│   ├── organization.ts
-│   └── event.ts
+│   └── organization.ts
 ├── types/                # TypeScript type definitions
 │   ├── calendar.types.ts
 │   ├── scheduling.types.ts
-│   └── internal.types.ts
+│   ├── internal.types.ts
+│   └── oauth.types.ts
 ├── typebox/              # Runtime validation schemas (auto-generated)
+│   ├── calendar.tb.ts
+│   ├── scheduling.tb.ts
+│   ├── oauth.tb.ts
+│   ├── organization.tb.ts
+│   ├── user.tb.ts
+│   ├── timeString.tb.ts
+│   ├── organization.stripped.tb.ts
+│   └── user.stripped.tb.ts
 ├── utils/                # Helper utilities
 │   ├── fetch.helper.ts
+│   ├── fetchErrorHandler.ts
 │   ├── includes.helper.ts
-│   └── functionize.ts
+│   ├── functionize.ts
+│   └── omit.ts
 └── errors.ts             # Custom error classes
 ```
 
@@ -589,7 +878,7 @@ bun run check:fix
 bun test
 
 # Run specific test file
-bun test tests/calendar.test.ts
+bun test tests/integrations/users.test.ts
 
 # Run with coverage
 bun test --coverage