151 lines
4.0 KiB
Markdown
151 lines
4.0 KiB
Markdown
---
|
|
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.
|