Calendar & Booking API Integration Guide

Purpose:

Check when a provider (tutor/coach) is available on a specific date.

Request Body:

{
  "user_id": "provider_user_id",
  "service_listing_id": "optional_service_id",
  "date": "2025-01-15"  // ISO date string
}

Response:

{
  "date": "2025-01-15T00:00:00.000Z",
  "day_of_week": 3,
  "available_slots": [
    {
      "start": "2025-01-15T14:00:00.000Z",
      "end": "2025-01-15T15:00:00.000Z",
      "display": "2:00 PM"
    },
    {
      "start": "2025-01-15T15:00:00.000Z",
      "end": "2025-01-15T16:00:00.000Z",
      "display": "3:00 PM"
    }
  ],
  "total_slots": 2
}

Example (JavaScript):

const response = await fetch('https://sphereus.com/functions/getAvailableSlots', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${userToken}`
  },
  body: JSON.stringify({
    user_id: providerId,
    date: '2025-01-15'
  })
});

const { available_slots } = await response.json();

Purpose:

Book a time slot. Automatically checks for conflicts and creates engagement records.

Request Body:

{
  "service_listing_id": "service_id",
  "provider_email": "tutor@example.com",
  "booking_date": "2025-01-15T14:00:00.000Z",  // ISO datetime
  "total_amount": 50,
  "payment_method": "su_coins",  // or "stripe", "cash"
  "notes": "Need help with algebra",
  "location": "Virtual - Zoom"
}

Success Response (200):

{
  "success": true,
  "booking": {
    "id": "booking_id",
    "service_listing_id": "...",
    "provider_email": "tutor@example.com",
    "customer_email": "student@example.com",
    "booking_date": "2025-01-15T14:00:00.000Z",
    "status": "pending",
    "payment_status": "pending",
    "total_amount": 50
  },
  "message": "Booking created successfully"
}

Conflict Response (409):

{
  "error": "Time slot conflict",
  "message": "This time slot is no longer available. Please choose another time."
}

Example (JavaScript):

const response = await fetch('https://sphereus.com/functions/createBookingWithConflictCheck', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${userToken}`
  },
  body: JSON.stringify({
    service_listing_id: serviceId,
    provider_email: 'tutor@example.com',
    booking_date: '2025-01-15T14:00:00.000Z',
    total_amount: 50,
    payment_method: 'su_coins',
    notes: 'Algebra help needed'
  })
});

if (response.status === 409) {
  alert('Time slot no longer available');
} else {
  const { booking } = await response.json();
  // Success!
}

Purpose:

Retrieve all bookings for a user (as customer or provider) across all divisions.

Query Parameters (Optional):

?user_email=user@example.com
&include_past=true

If no params provided, uses authenticated user's data.

Response:

{
  "bookings": [
    {
      "id": "...",
      "service_name": "Algebra Tutoring",
      "service_category": "tutoring",
      "booking_date": "2025-01-15T14:00:00.000Z",
      "status": "confirmed",
      "role": "customer",  // or "provider"
      "is_past": false,
      "provider_email": "tutor@example.com",
      "customer_email": "student@example.com"
    }
  ],
  "total": 5,
  "as_customer": 3,
  "as_provider": 2,
  "upcoming": 4,
  "past": 1
}

Example (JavaScript):

const response = await fetch('https://sphereus.com/functions/getUserBookings', {
  headers: {
    'Authorization': `Bearer ${userToken}`
  }
});

const { bookings, upcoming } = await response.json();

Purpose:

Get provider's weekly schedule, exceptions, and booked slots.

Request Body:

{
  "provider_email": "tutor@example.com",
  "start_date": "2025-01-01",  // optional
  "end_date": "2025-01-31"     // optional
}

Response:

{
  "provider_email": "tutor@example.com",
  "provider_name": "Jane Smith",
  "weekly_schedule": {
    "1": [
      { "start_time": "09:00", "end_time": "17:00" }
    ],
    "2": [
      { "start_time": "09:00", "end_time": "17:00" }
    ]
  },
  "exceptions": [
    {
      "date": "2025-01-20",
      "end_date": null,
      "notes": "Holiday - Closed"
    }
  ],
  "upcoming_bookings": [...],
  "total_bookings": 5,
  "is_available": true
}

Purpose:

Add an event directly to a member's SphereUs calendar (for BudVan rides, deliveries, etc.)

Request Body:

{
  "user_email": "driver@example.com",     // Optional, defaults to current user
  "title": "BudVan Ride - Airport Pickup",
  "description": "Pickup John from Miami Airport",
  "event_type": "other",                  // or "community_event", etc.
  "division": "BudVan",
  "start_datetime": "2025-01-15T14:00:00.000Z",
  "end_datetime": "2025-01-15T15:30:00.000Z",
  "location": "Miami International Airport",
  "is_virtual": false,
  "metadata": {                           // Optional custom data
    "ride_id": "ride_123",
    "passenger_name": "John Doe"
  }
}

Response:

{
  "success": true,
  "event": {
    "id": "event_id",
    "title": "BudVan Ride - Airport Pickup",
    "start_datetime": "2025-01-15T14:00:00.000Z",
    "end_datetime": "2025-01-15T15:30:00.000Z",
    "user_email": "driver@example.com"
  },
  "message": "Calendar event added successfully"
}

Example (JavaScript):

// Add to driver's calendar when they accept a ride
const response = await fetch('https://sphereus.com/functions/addCalendarEvent', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${driverToken}`
  },
  body: JSON.stringify({
    user_email: driverEmail,
    title: 'BudVan Ride - Airport Pickup',
    description: `Pickup ${passengerName} from ${pickupLocation}`,
    division: 'BudVan',
    start_datetime: rideStartTime,
    end_datetime: rideEndTime,
    location: pickupLocation,
    metadata: { ride_id: rideId }
  })
});

const { event } = await response.json();

Request Body:

{
  "event_id": "event_id",
  "updates": {
    "title": "Updated Title",
    "start_datetime": "2025-01-15T15:00:00.000Z",
    "status": "cancelled"
  }
}

Request Body:

{
  "event_id": "event_id"
}