---
name: mosaic-plugin-calendar
description: Integration with Mosaic Stack's Events API for calendar management. Use when the user wants to schedule, view, update, or cancel events/meetings/appointments in their Mosaic calendar, including queries like "schedule a meeting", "what's on my calendar", "upcoming events", "cancel meeting", or "reschedule appointment".
---

# Mosaic Calendar

Integration with Mosaic Stack's Events API for comprehensive calendar management.

## Quick Start

Use `scripts/calendar.js` for all calendar operations. The script handles authentication and API communication automatically.

### Creating Events

```bash
node scripts/calendar.js create \
  --title "Team Meeting" \
  --start "2024-01-30T15:00:00Z" \
  --end "2024-01-30T16:00:00Z" \
  --description "Weekly sync" \
  --location "Conference Room A"
```

Natural language examples:
- "Schedule a meeting tomorrow at 3pm"
- "Create an event called 'dentist appointment' on Friday at 2pm"
- "Add a recurring standup every weekday at 9am"

### Querying Events

```bash
# List all upcoming events
node scripts/calendar.js list

# Events in a date range
node scripts/calendar.js list \
  --from "2024-01-30" \
  --to "2024-02-05"

# Events for a specific project
node scripts/calendar.js list --project-id "uuid-here"
```

Natural language examples:
- "What's on my calendar this week?"
- "Show me upcoming events"
- "What do I have scheduled for tomorrow?"
- "Any meetings today?"

### Updating Events

```bash
node scripts/calendar.js update EVENT_ID \
  --title "Updated Title" \
  --start "2024-01-30T16:00:00Z"
```

Natural language examples:
- "Move my 3pm meeting to 4pm"
- "Reschedule tomorrow's dentist appointment to Friday"
- "Change the location of my team meeting to Zoom"

### Deleting Events

```bash
node scripts/calendar.js delete EVENT_ID
```

Natural language examples:
- "Cancel my meeting with Sarah"
- "Delete tomorrow's standup"
- "Remove the 3pm appointment"

## Event Fields

- **title** (required): Event name (1-255 characters)
- **startTime** (required): ISO 8601 date string (e.g., "2024-01-30T15:00:00Z")
- **endTime** (optional): ISO 8601 date string
- **description** (optional): Event details (max 10,000 characters)
- **location** (optional): Physical or virtual location (max 500 characters)
- **allDay** (optional): Boolean flag for all-day events
- **recurrence** (optional): Recurrence rules (object)
- **projectId** (optional): Link event to a Mosaic project (UUID)
- **metadata** (optional): Custom key-value data (object)

## Date Handling

When processing natural language date/time requests:

1. Convert to ISO 8601 format (e.g., "2024-01-30T15:00:00Z")
2. Handle relative dates ("tomorrow", "next week", "Friday")
3. Infer end time if not specified (default: 1 hour after start)
4. Use user's timezone (America/Chicago) unless specified otherwise

## Response Format

All operations return JSON:

```json
{
  "id": "uuid",
  "title": "Team Meeting",
  "startTime": "2024-01-30T15:00:00Z",
  "endTime": "2024-01-30T16:00:00Z",
  "description": "Weekly sync",
  "location": "Conference Room A",
  "allDay": false,
  "workspaceId": "uuid",
  "createdBy": "uuid",
  "projectId": null,
  "recurrence": null,
  "metadata": {},
  "createdAt": "2024-01-29T10:00:00Z",
  "updatedAt": "2024-01-29T10:00:00Z"
}
```

List queries return paginated results with metadata:

```json
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 100,
    "totalPages": 2
  }
}
```

## Environment

The script reads configuration from:
- `MOSAIC_API_URL` (default: http://localhost:3001)
- `MOSAIC_WORKSPACE_ID` (required)
- `MOSAIC_API_TOKEN` (required for authentication)

Ensure these are set in the environment or `.env` file.

## Error Handling

Common errors:
- **401 Unauthorized**: Missing or invalid API token
- **403 Forbidden**: Insufficient workspace permissions
- **404 Not Found**: Event ID doesn't exist
- **400 Bad Request**: Invalid date format or missing required fields

When operations fail, the script outputs clear error messages with guidance on resolution.