botserver/docs/src/chapter-10-api/calendar-api.md

Calendar API

The Calendar API provides endpoints for managing events, schedules, and time-based activities within BotServer.

Status

⚠️ NOT IMPLEMENTED

This API is planned for future development but is not currently available in BotServer.

Planned Features

The Calendar API will enable:

• Event creation and management
• Meeting scheduling
• Availability checking
• Recurring events
• Calendar synchronization
• Reminders and notifications

Planned Endpoints

Event Management

• POST /api/v1/calendar/events - Create event
• GET /api/v1/calendar/events - List events
• GET /api/v1/calendar/events/{event_id} - Get event details
• PATCH /api/v1/calendar/events/{event_id} - Update event
• DELETE /api/v1/calendar/events/{event_id} - Delete event

Scheduling

• POST /api/v1/calendar/schedule - Find available time slots
• POST /api/v1/calendar/meeting - Schedule meeting
• GET /api/v1/calendar/availability - Check availability

Recurring Events

• POST /api/v1/calendar/events/recurring - Create recurring event
• PATCH /api/v1/calendar/events/{event_id}/recurrence - Update recurrence

Reminders

• POST /api/v1/calendar/events/{event_id}/reminders - Add reminder
• GET /api/v1/calendar/reminders - List upcoming reminders

Planned Integration with BASIC

When implemented, calendar features will be accessible via BASIC keywords:

' Create event (not yet available)
event_id = CREATE EVENT "Team Meeting", "2024-02-01 14:00"
SET EVENT DURATION event_id, 60  ' 60 minutes

' Check availability (not yet available)
available = CHECK AVAILABILITY "user123", "2024-02-01"
IF available THEN
    TALK "User is available"
END IF

' Schedule meeting (not yet available)
meeting_id = SCHEDULE MEETING participants, datetime, duration
SEND INVITES meeting_id

Planned Data Models

Event

{
  "event_id": "evt_123",
  "title": "Team Meeting",
  "description": "Weekly sync",
  "start_time": "2024-02-01T14:00:00Z",
  "end_time": "2024-02-01T15:00:00Z",
  "location": "Conference Room A",
  "attendees": ["user123", "user456"],
  "recurrence": {
    "frequency": "weekly",
    "interval": 1,
    "days_of_week": ["monday"],
    "end_date": "2024-12-31"
  },
  "reminders": [
    {"minutes_before": 15, "method": "notification"},
    {"minutes_before": 60, "method": "email"}
  ]
}

Availability

{
  "user_id": "user123",
  "date": "2024-02-01",
  "time_slots": [
    {"start": "09:00", "end": "10:00", "available": true},
    {"start": "10:00", "end": "11:00", "available": false},
    {"start": "11:00", "end": "12:00", "available": true}
  ]
}

Planned Features Detail

Event Types

• Single Events: One-time occurrences
• Recurring Events: Daily, weekly, monthly patterns
• All-day Events: Full day events without specific times
• Multi-day Events: Events spanning multiple days

Notification Methods

• In-app notifications
• Email reminders
• SMS alerts (when configured)
• Bot messages

Calendar Views

• Day view
• Week view
• Month view
• Agenda view

Time Zone Support

• User-specific time zones
• Automatic DST handling
• Cross-timezone meeting coordination

Integration Points

• External calendar systems (Google, Outlook)
• Video conferencing platforms
• Task management system
• Notification system

Implementation Considerations

When implemented, the Calendar API will:

1. Use PostgreSQL for event storage
2. Support iCal format for import/export
3. Handle time zones properly
4. Provide conflict detection for scheduling
5. Include RBAC for event management
6. Support delegation for assistants
7. Enable calendar sharing between users

Alternative Solutions

Until the Calendar API is implemented, consider:

1. External Calendar Services

   • Integrate with Google Calendar API
   • Use Microsoft Graph API for Outlook
   • Connect to CalDAV servers

2. Simple Scheduling in BASIC

   ' Store appointments in bot memory
   appointment = "Meeting with client at 2 PM"
   SET BOT MEMORY "appointment_" + date, appointment
   
   ' Retrieve appointments
   today_appointment = GET BOT MEMORY "appointment_" + TODAY()
   IF today_appointment <> "" THEN
       TALK "Today's appointment: " + today_appointment
   END IF
   

3. Task-based Scheduling

   • Use the Tasks API with due dates
   • Create tasks for time-sensitive items
   • Set reminders via scheduled BASIC scripts

Future Integration

The Calendar API will integrate with:

• Tasks API - Link tasks to calendar events
• Notifications API - Event reminders
• User API - User availability
• Meeting API (future) - Video conferencing

Workaround Example

Until the Calendar API is available, you can implement basic scheduling:

' Simple appointment booking system
FUNCTION BookAppointment(date, time, description)
    key = "appointment_" + date + "_" + time
    existing = GET BOT MEMORY key
    
    IF existing = "" THEN
        SET BOT MEMORY key, description
        TALK "Appointment booked for " + date + " at " + time
        RETURN TRUE
    ELSE
        TALK "That time slot is already taken"
        RETURN FALSE
    END IF
END FUNCTION

' Check availability
FUNCTION CheckAvailability(date)
    slots = ["09:00", "10:00", "11:00", "14:00", "15:00", "16:00"]
    available = []
    
    FOR EACH slot IN slots
        key = "appointment_" + date + "_" + slot
        appointment = GET BOT MEMORY key
        IF appointment = "" THEN
            available = APPEND(available, slot)
        END IF
    NEXT
    
    RETURN available
END FUNCTION

Status Updates

Check the GitHub repository for updates on Calendar API implementation status.