@miguelarios/cal-mcp 0.20.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/CHANGELOG.md +51 -0
  2. package/LICENSE +21 -0
  3. package/README.md +8 -3
  4. package/dist/main.d.ts +2 -2
  5. package/dist/main.d.ts.map +1 -1
  6. package/dist/main.js +1 -1
  7. package/dist/main.js.map +1 -1
  8. package/dist/providers/CalendarBackend.d.ts +94 -0
  9. package/dist/providers/CalendarBackend.d.ts.map +1 -0
  10. package/dist/providers/CalendarBackend.js +2 -0
  11. package/dist/providers/CalendarBackend.js.map +1 -0
  12. package/dist/providers/types.d.ts +98 -0
  13. package/dist/providers/types.d.ts.map +1 -0
  14. package/dist/providers/types.js +2 -0
  15. package/dist/providers/types.js.map +1 -0
  16. package/dist/services/CalDavService.d.ts +40 -92
  17. package/dist/services/CalDavService.d.ts.map +1 -1
  18. package/dist/services/CalDavService.js +210 -64
  19. package/dist/services/CalDavService.js.map +1 -1
  20. package/dist/services/sharing.d.ts +39 -0
  21. package/dist/services/sharing.d.ts.map +1 -0
  22. package/dist/services/sharing.js +253 -0
  23. package/dist/services/sharing.js.map +1 -0
  24. package/dist/services/urlCache.d.ts +1 -1
  25. package/dist/services/urlCache.js +2 -2
  26. package/dist/services/urlCache.js.map +1 -1
  27. package/dist/tools/calendarManagementTools.d.ts +3 -3
  28. package/dist/tools/calendarManagementTools.d.ts.map +1 -1
  29. package/dist/tools/calendarManagementTools.js +108 -33
  30. package/dist/tools/calendarManagementTools.js.map +1 -1
  31. package/dist/tools/calendarSchemas.d.ts +67 -45
  32. package/dist/tools/calendarSchemas.d.ts.map +1 -1
  33. package/dist/tools/calendarSchemas.js +35 -14
  34. package/dist/tools/calendarSchemas.js.map +1 -1
  35. package/dist/tools/calendarTools.d.ts +2 -2
  36. package/dist/tools/calendarTools.d.ts.map +1 -1
  37. package/dist/tools/calendarTools.js +160 -112
  38. package/dist/tools/calendarTools.js.map +1 -1
  39. package/package.json +8 -4
@@ -1,8 +1,8 @@
1
1
  import { randomUUID } from "node:crypto";
2
- import { getLocalDateParts, getTimezone, zonedTimeToUtc } from "@miguelarios/pim-core";
3
- import { addExdateToIcs, combineIcsComponents, createExceptionComponent, formatTriggerHuman, generateEventIcs, removeExceptionFromIcs, splitIcsByUid, splitRecurrenceIcs, truncateRecurrenceIcs, updateMasterEventIcs, } from "@miguelarios/pim-core/ics";
2
+ import { ErrorCode, getLocalDateParts, getTimezone, zonedTimeToUtc } from "@miguelarios/pim-core";
3
+ import { IcsGenerateError, IcsParseError, addExdateToIcs, combineIcsComponents, createExceptionComponent, formatTriggerHuman, generateEventIcs, removeExceptionFromIcs, splitIcsByUid, splitRecurrenceIcs, truncateRecurrenceIcs, updateMasterEventIcs, } from "@miguelarios/pim-core/ics";
4
4
  import { confirmDestructive, fail, structured, toolError, } from "@miguelarios/pim-core/mcp";
5
- import { drainDebugTimings, } from "../services/CalDavService.js";
5
+ import { drainDebugTimings } from "../services/CalDavService.js";
6
6
  import { batchCreateSchema, calendarListSchema, deleteResultSchema, eventListSchema, freeBusySchema, freeSlotsSchema, importResultSchema, singleEventSchema, } from "./calendarSchemas.js";
7
7
  /**
8
8
  * The `update_event` fields that are forwarded verbatim to the ICS layer on
@@ -14,7 +14,7 @@ const UPDATABLE_FIELDS = [
14
14
  "title",
15
15
  "start",
16
16
  "end",
17
- "all_day",
17
+ "allDay",
18
18
  "location",
19
19
  "description",
20
20
  "attendees",
@@ -37,14 +37,27 @@ function selectedCalendars(args) {
37
37
  const ids = [...(args.calendars ?? []), ...(args.calendar ? [args.calendar] : [])];
38
38
  return [...new Set(ids)];
39
39
  }
40
+ /** Spread into a listing result: the providers it skipped, when there were any. */
41
+ function unavailableField(unavailable) {
42
+ return unavailable.length > 0 ? { unavailableProviders: unavailable } : {};
43
+ }
44
+ /**
45
+ * Events in [start, end) on the selected calendars, or on every reachable
46
+ * calendar when none is selected. An unreachable provider is skipped and
47
+ * reported only in that second case: a calendar the caller named explicitly
48
+ * still fails the call if it cannot be read.
49
+ */
40
50
  async function fetchEvents(service, selection, start, end, detailLevel) {
41
51
  const full = detailLevel === "full";
42
52
  let calendarIds = selectedCalendars(selection);
53
+ let unavailable = [];
43
54
  if (calendarIds.length === 0) {
44
- calendarIds = (await service.listCalendars()).map((cal) => cal.calendar_id);
55
+ const reachable = await service.listReachableCalendars();
56
+ calendarIds = reachable.calendars.map((cal) => cal.calendarId);
57
+ unavailable = reachable.unavailable;
45
58
  }
46
59
  const results = await Promise.all(calendarIds.map((id) => full ? service.listEventsFull(id, start, end) : service.listEvents(id, start, end)));
47
- return results.flat();
60
+ return { events: results.flat(), unavailable };
48
61
  }
49
62
  /**
50
63
  * Timing diagnostics ride in the result's `_meta` rather than inside the
@@ -64,22 +77,33 @@ function ok(payload) {
64
77
  function calFail(code, message, retryable = false) {
65
78
  return { ...fail(code, message, retryable), ...debugMeta() };
66
79
  }
80
+ /** A `VALIDATION_FAILED` result unless `start` and `end` parse and `start` comes first. */
81
+ function checkRange(start, end) {
82
+ const startMs = new Date(start).getTime();
83
+ const endMs = new Date(end).getTime();
84
+ if (Number.isNaN(startMs) || Number.isNaN(endMs) || startMs >= endMs) {
85
+ return calFail(ErrorCode.VALIDATION_FAILED, "start and end must be ISO 8601 with start before end");
86
+ }
87
+ return undefined;
88
+ }
67
89
  /**
68
- * Preserves this server's external error vocabulary (`not_found`,
69
- * `validation_error`, `backend_error`) while letting the underlying
70
- * `PimError` message through.
90
+ * A `VALIDATION_FAILED` result unless `occurrenceDate` parses. Checked before
91
+ * anything is written: an unparseable date reaches the ICS helpers as `NaN`,
92
+ * and `addExdateToIcs` would store `EXDATE:NaN-aNNaN…` on the server.
71
93
  */
72
- function mapError(err) {
73
- if (err && typeof err === "object" && "code" in err) {
74
- const code = err.code;
75
- if (code === "CALENDAR_NOT_FOUND" || code === "EVENT_NOT_FOUND") {
76
- return { ...toolError(err, () => "not_found"), ...debugMeta() };
77
- }
78
- if (code === "VALIDATION_FAILED") {
79
- return { ...toolError(err, () => "validation_error"), ...debugMeta() };
80
- }
94
+ function checkOccurrenceDate(occurrenceDate) {
95
+ if (Number.isNaN(new Date(occurrenceDate).getTime())) {
96
+ return calFail(ErrorCode.VALIDATION_FAILED, `Invalid occurrenceDate "${occurrenceDate}" — use an ISO 8601 date-time`);
81
97
  }
82
- return { ...toolError(err, () => "backend_error"), ...debugMeta() };
98
+ return undefined;
99
+ }
100
+ /**
101
+ * Reports a thrown error with its pim-core `ErrorCode` (`CALENDAR_NOT_FOUND`,
102
+ * `VALIDATION_FAILED`, `CONNECTION_FAILED`, …), the same vocabulary card-mcp
103
+ * and email-mcp return.
104
+ */
105
+ function mapError(err) {
106
+ return { ...toolError(err), ...debugMeta() };
83
107
  }
84
108
  /**
85
109
  * Widens an attendee from the tool's input shape (`{ email }`) to the shape a
@@ -96,11 +120,11 @@ function toResponseAttendee(attendee) {
96
120
  type: "person",
97
121
  };
98
122
  }
99
- /** Widens an alarm from the tool's input shape by rendering `trigger_human`. */
123
+ /** Widens an alarm from the tool's input shape by rendering `triggerHuman`. */
100
124
  function toResponseAlarm(alarm) {
101
125
  return {
102
126
  ...alarm,
103
- trigger_human: alarm.type === "absolute"
127
+ triggerHuman: alarm.type === "absolute"
104
128
  ? new Date(alarm.trigger).toISOString()
105
129
  : formatTriggerHuman(Number(alarm.trigger)),
106
130
  };
@@ -177,7 +201,10 @@ export const CALENDAR_TOOLS = [
177
201
  annotations: READ_ONLY,
178
202
  inputSchema: { type: "object", properties: {} },
179
203
  outputSchema: calendarListSchema,
180
- handler: (_args, service) => run(async () => ok({ calendars: await service.listCalendars() })),
204
+ handler: (_args, service) => run(async () => {
205
+ const { calendars, unavailable } = await service.listReachableCalendars();
206
+ return ok({ calendars, ...unavailableField(unavailable) });
207
+ }),
181
208
  },
182
209
  {
183
210
  name: "list_events",
@@ -194,14 +221,18 @@ export const CALENDAR_TOOLS = [
194
221
  calendars: CALENDARS_PROP("query"),
195
222
  start: { type: "string", description: "Start of date range (ISO 8601)" },
196
223
  end: { type: "string", description: "End of date range (ISO 8601)" },
197
- detail_level: DETAIL_LEVEL_PROP,
224
+ detailLevel: DETAIL_LEVEL_PROP,
198
225
  },
199
226
  required: ["start", "end"],
200
227
  },
201
228
  outputSchema: eventListSchema,
202
- handler: (args, service) => run(async () => ok({
203
- events: await fetchEvents(service, args, args.start, args.end, args.detail_level ?? "summary"),
204
- })),
229
+ handler: (args, service) => run(async () => {
230
+ const invalid = checkRange(args.start, args.end);
231
+ if (invalid)
232
+ return invalid;
233
+ const { events, unavailable } = await fetchEvents(service, args, args.start, args.end, args.detailLevel ?? "summary");
234
+ return ok({ events, ...unavailableField(unavailable) });
235
+ }),
205
236
  },
206
237
  {
207
238
  name: "get_today_events",
@@ -216,7 +247,7 @@ export const CALENDAR_TOOLS = [
216
247
  description: "Provider-prefixed calendar ID. If omitted, queries all calendars.",
217
248
  },
218
249
  calendars: CALENDARS_PROP("query"),
219
- detail_level: DETAIL_LEVEL_PROP,
250
+ detailLevel: DETAIL_LEVEL_PROP,
220
251
  },
221
252
  },
222
253
  outputSchema: eventListSchema,
@@ -225,9 +256,8 @@ export const CALENDAR_TOOLS = [
225
256
  const { year, month, day } = getLocalDateParts(new Date(), tz);
226
257
  const todayStart = zonedTimeToUtc(year, month, day, 0, 0, tz).toISOString();
227
258
  const todayEnd = zonedTimeToUtc(year, month, day + 1, 0, 0, tz).toISOString();
228
- return ok({
229
- events: await fetchEvents(service, args, todayStart, todayEnd, args.detail_level ?? "summary"),
230
- });
259
+ const { events, unavailable } = await fetchEvents(service, args, todayStart, todayEnd, args.detailLevel ?? "summary");
260
+ return ok({ events, ...unavailableField(unavailable) });
231
261
  }),
232
262
  },
233
263
  {
@@ -252,38 +282,41 @@ export const CALENDAR_TOOLS = [
252
282
  type: "string",
253
283
  description: "Range end (ISO 8601). Defaults to 90 days ahead.",
254
284
  },
255
- detail_level: DETAIL_LEVEL_PROP,
285
+ detailLevel: DETAIL_LEVEL_PROP,
256
286
  },
257
287
  required: ["query"],
258
288
  },
259
289
  outputSchema: eventListSchema,
260
290
  handler: (args, service) => run(async () => {
261
291
  const query = args.query.toLowerCase();
262
- const detailLevel = args.detail_level ?? "summary";
292
+ const detailLevel = args.detailLevel ?? "summary";
263
293
  const now = new Date();
264
294
  const start = args.start ?? new Date(now.getTime() - 90 * 86400000).toISOString();
265
295
  const end = args.end ?? new Date(now.getTime() + 90 * 86400000).toISOString();
266
- const events = await fetchEvents(service, args, start, end, detailLevel);
296
+ const invalid = checkRange(start, end);
297
+ if (invalid)
298
+ return invalid;
299
+ const { events, unavailable } = await fetchEvents(service, args, start, end, detailLevel);
267
300
  const matched = events.filter((e) => {
268
301
  const title = e.title?.toLowerCase() ?? "";
269
302
  const location = e.location?.toLowerCase() ?? "";
270
303
  const description = detailLevel === "full" ? (e.description?.toLowerCase() ?? "") : "";
271
304
  return title.includes(query) || location.includes(query) || description.includes(query);
272
305
  });
273
- return ok({ events: matched });
306
+ return ok({ events: matched, ...unavailableField(unavailable) });
274
307
  }),
275
308
  },
276
309
  {
277
310
  name: "get_event",
278
311
  title: "Get Event",
279
- description: "Get full details of a single event by calendar and UID. For a recurring event, pass occurrence_date to get one occurrence as it will actually happen — including any changes made to just that occurrence — instead of the master series.",
312
+ description: "Get full details of a single event by calendar and UID. For a recurring event, pass occurrenceDate to get one occurrence as it will actually happen — including any changes made to just that occurrence — instead of the master series.",
280
313
  annotations: READ_ONLY,
281
314
  inputSchema: {
282
315
  type: "object",
283
316
  properties: {
284
317
  calendar: CALENDAR_PROP,
285
318
  uid: { type: "string", description: "Event UID" },
286
- occurrence_date: {
319
+ occurrenceDate: {
287
320
  type: "string",
288
321
  description: "ISO 8601 date-time of one occurrence of a recurring event, as returned in list_events results. Returns that occurrence (with any per-occurrence overrides applied) rather than the master series. Omit to get the master.",
289
322
  },
@@ -291,7 +324,7 @@ export const CALENDAR_TOOLS = [
291
324
  required: ["calendar", "uid"],
292
325
  },
293
326
  outputSchema: singleEventSchema,
294
- handler: (args, service) => run(async () => ok({ event: await service.getEvent(args.calendar, args.uid, args.occurrence_date) })),
327
+ handler: (args, service) => run(async () => ok({ event: await service.getEvent(args.calendar, args.uid, args.occurrenceDate) })),
295
328
  },
296
329
  {
297
330
  name: "create_event",
@@ -310,13 +343,13 @@ export const CALENDAR_TOOLS = [
310
343
  title: { type: "string", description: "Event title" },
311
344
  start: { type: "string", description: "Start time (ISO 8601)" },
312
345
  end: { type: "string", description: "End time (ISO 8601)" },
313
- all_day: { type: "boolean", description: "All-day event flag (default: false)" },
346
+ allDay: { type: "boolean", description: "All-day event flag (default: false)" },
314
347
  location: { type: "string", description: "Event location" },
315
348
  description: { type: "string", description: "Event description" },
316
349
  attendees: ATTENDEES_PROP("List of attendee email addresses to invite."),
317
350
  alarms: ALARMS_PROP,
318
351
  categories: CATEGORIES_PROP,
319
- recurrence_rule: {
352
+ recurrenceRule: {
320
353
  type: "string",
321
354
  description: "RFC 5545 RRULE string for a recurring event (e.g., 'FREQ=WEEKLY;BYDAY=MO,WE,FR' or 'FREQ=MONTHLY;BYDAY=+3FR;COUNT=12'). Accepted with or without the 'RRULE:' prefix. FREQ is required.",
322
355
  },
@@ -340,13 +373,13 @@ export const CALENDAR_TOOLS = [
340
373
  title: args.title,
341
374
  start: args.start,
342
375
  end: args.end,
343
- all_day: args.all_day ?? false,
376
+ allDay: args.allDay ?? false,
344
377
  location: args.location,
345
378
  description: args.description,
346
379
  attendees: args.attendees,
347
380
  alarms: args.alarms,
348
381
  categories: args.categories,
349
- recurrence_rule: args.recurrence_rule,
382
+ recurrenceRule: args.recurrenceRule,
350
383
  organizer,
351
384
  availability: args.availability,
352
385
  timezone: getTimezone(),
@@ -356,8 +389,8 @@ export const CALENDAR_TOOLS = [
356
389
  return ok({ event: await service.createEvent(args.calendar, icsString, uid) });
357
390
  }
358
391
  catch (err) {
359
- if (err instanceof Error && err.message.startsWith("Invalid recurrence_rule:")) {
360
- return calFail("validation_error", err.message);
392
+ if (err instanceof IcsGenerateError) {
393
+ return calFail(ErrorCode.VALIDATION_FAILED, err.message);
361
394
  }
362
395
  throw err;
363
396
  }
@@ -381,13 +414,13 @@ export const CALENDAR_TOOLS = [
381
414
  title: { type: "string", description: "New event title" },
382
415
  start: { type: "string", description: "New start time (ISO 8601)" },
383
416
  end: { type: "string", description: "New end time (ISO 8601)" },
384
- all_day: { type: "boolean", description: "All-day event flag" },
417
+ allDay: { type: "boolean", description: "All-day event flag" },
385
418
  location: { type: "string", description: "New location" },
386
419
  description: { type: "string", description: "New description" },
387
420
  attendees: ATTENDEES_PROP("New attendee list (replaces existing)."),
388
421
  alarms: ALARMS_PROP,
389
422
  categories: CATEGORIES_PROP,
390
- occurrence_date: {
423
+ occurrenceDate: {
391
424
  type: "string",
392
425
  description: "ISO 8601 date of the specific occurrence to modify. Required when span is 'this' or 'future' on a recurring event. Get this value from list_events results.",
393
426
  },
@@ -409,11 +442,14 @@ export const CALENDAR_TOOLS = [
409
442
  const span = args.span ?? "this";
410
443
  const { event: existing } = await service.getEventWithMeta(args.calendar, args.uid);
411
444
  // span="this" on a recurring event: create exception VEVENT
412
- if (existing.is_recurring && span === "this") {
413
- if (!args.occurrence_date) {
414
- return calFail("validation_error", "occurrence_date is required when span is 'this' on a recurring event");
445
+ if (existing.isRecurring && span === "this") {
446
+ if (!args.occurrenceDate) {
447
+ return calFail(ErrorCode.VALIDATION_FAILED, "occurrenceDate is required when span is 'this' on a recurring event");
415
448
  }
416
- const occurrenceDate = args.occurrence_date;
449
+ const occurrenceDate = args.occurrenceDate;
450
+ const invalidDate = checkOccurrenceDate(occurrenceDate);
451
+ if (invalidDate)
452
+ return invalidDate;
417
453
  const rawObj = await service.fetchRawCalendarObject(args.calendar, args.uid);
418
454
  const overrides = {};
419
455
  for (const field of UPDATABLE_FIELDS)
@@ -424,7 +460,7 @@ export const CALENDAR_TOOLS = [
424
460
  if (effectiveAttendees && effectiveAttendees.length > 0 && !existing.organizer) {
425
461
  overrides.organizer = { email: service.getAccountEmail(args.calendar) };
426
462
  }
427
- const exceptionVevent = createExceptionComponent(rawObj.data, "vevent", occurrenceDate, overrides, existing.all_day);
463
+ const exceptionVevent = createExceptionComponent(rawObj.data, "vevent", occurrenceDate, overrides, existing.allDay);
428
464
  const combinedIcs = combineIcsComponents(rawObj.data, exceptionVevent);
429
465
  await service.updateEvent(args.calendar, args.uid, combinedIcs, {
430
466
  url: rawObj.url,
@@ -443,7 +479,7 @@ export const CALENDAR_TOOLS = [
443
479
  start: overrides.start ?? occurrenceDate,
444
480
  end: overrides.end ??
445
481
  new Date(new Date(occurrenceDate).getTime() + occDuration).toISOString(),
446
- all_day: overrides.all_day ?? existing.all_day,
482
+ allDay: overrides.allDay ?? existing.allDay,
447
483
  location: overrides.location ?? existing.location,
448
484
  description: overrides.description ?? existing.description,
449
485
  attendees: overrides.attendees
@@ -454,8 +490,8 @@ export const CALENDAR_TOOLS = [
454
490
  ? { name: overrides.organizer.name ?? null, email: overrides.organizer.email }
455
491
  : existing.organizer,
456
492
  categories: overrides.categories ?? existing.categories,
457
- occurrence_date: occurrenceDate,
458
- recurrence_rule: null,
493
+ occurrenceDate: occurrenceDate,
494
+ recurrenceRule: null,
459
495
  },
460
496
  });
461
497
  }
@@ -474,22 +510,22 @@ export const CALENDAR_TOOLS = [
474
510
  // (new UID) carries the remaining pattern with the changes applied.
475
511
  // A cut at the first occurrence has nothing to keep behind it, so it
476
512
  // falls through to the whole-series edit below (#38).
477
- if (existing.is_recurring && span === "future") {
478
- if (!args.occurrence_date) {
479
- return calFail("validation_error", "occurrence_date is required when span is 'future' on a recurring event");
480
- }
481
- const occurrenceDate = args.occurrence_date;
482
- if (Number.isNaN(new Date(occurrenceDate).getTime())) {
483
- return calFail("validation_error", `Invalid occurrence_date "${occurrenceDate}" — use an ISO 8601 date-time`);
513
+ if (existing.isRecurring && span === "future") {
514
+ if (!args.occurrenceDate) {
515
+ return calFail(ErrorCode.VALIDATION_FAILED, "occurrenceDate is required when span is 'future' on a recurring event");
484
516
  }
517
+ const occurrenceDate = args.occurrenceDate;
518
+ const invalidDate = checkOccurrenceDate(occurrenceDate);
519
+ if (invalidDate)
520
+ return invalidDate;
485
521
  const newUid = `${randomUUID()}@pim-core`;
486
522
  let split;
487
523
  try {
488
- split = splitRecurrenceIcs(rawObj.data, occurrenceDate, existing.all_day, newUid);
524
+ split = splitRecurrenceIcs(rawObj.data, occurrenceDate, existing.allDay, newUid);
489
525
  }
490
526
  catch (err) {
491
527
  if (err instanceof Error && err.message.startsWith("No occurrence at")) {
492
- return calFail("validation_error", err.message);
528
+ return calFail(ErrorCode.VALIDATION_FAILED, err.message);
493
529
  }
494
530
  throw err;
495
531
  }
@@ -548,18 +584,18 @@ export const CALENDAR_TOOLS = [
548
584
  properties: {
549
585
  calendar: CALENDAR_PROP,
550
586
  uid: { type: "string", description: "Event UID to move" },
551
- target_calendar: {
587
+ targetCalendar: {
552
588
  type: "string",
553
589
  description: "Destination provider-prefixed calendar ID, on the same account",
554
590
  },
555
591
  },
556
- required: ["calendar", "uid", "target_calendar"],
592
+ required: ["calendar", "uid", "targetCalendar"],
557
593
  },
558
594
  outputSchema: singleEventSchema,
559
595
  handler: (args, service) => run(async () => {
560
596
  const { meta } = await service.getEventWithMeta(args.calendar, args.uid);
561
597
  return ok({
562
- event: await service.moveEvent(args.calendar, args.uid, args.target_calendar, meta),
598
+ event: await service.moveEvent(args.calendar, args.uid, args.targetCalendar, meta),
563
599
  });
564
600
  }),
565
601
  },
@@ -578,7 +614,7 @@ export const CALENDAR_TOOLS = [
578
614
  properties: {
579
615
  calendar: CALENDAR_PROP,
580
616
  uid: { type: "string", description: "Event UID to delete" },
581
- occurrence_date: {
617
+ occurrenceDate: {
582
618
  type: "string",
583
619
  description: "ISO 8601 date of the specific occurrence to delete. Required when span is 'this' or 'future' on a recurring event. Get this value from list_events results.",
584
620
  },
@@ -600,18 +636,18 @@ export const CALENDAR_TOOLS = [
600
636
  if (span === "future") {
601
637
  return run(async () => {
602
638
  const { event: existing, meta: eventMeta } = await service.getEventWithMeta(args.calendar, args.uid);
603
- if (!existing.is_recurring) {
604
- return calFail("validation_error", `Event "${args.uid}" is not recurring — use span 'all' to delete it`);
605
- }
606
- if (!args.occurrence_date) {
607
- return calFail("validation_error", "occurrence_date is required when span is 'future' on a recurring event");
639
+ if (!existing.isRecurring) {
640
+ return calFail(ErrorCode.VALIDATION_FAILED, `Event "${args.uid}" is not recurring — use span 'all' to delete it`);
608
641
  }
609
- const occurrenceDate = args.occurrence_date;
610
- if (Number.isNaN(new Date(occurrenceDate).getTime())) {
611
- return calFail("validation_error", `Invalid occurrence_date "${occurrenceDate}" — use an ISO 8601 date-time`);
642
+ if (!args.occurrenceDate) {
643
+ return calFail(ErrorCode.VALIDATION_FAILED, "occurrenceDate is required when span is 'future' on a recurring event");
612
644
  }
645
+ const occurrenceDate = args.occurrenceDate;
646
+ const invalidDate = checkOccurrenceDate(occurrenceDate);
647
+ if (invalidDate)
648
+ return invalidDate;
613
649
  const rawObj = await service.fetchRawCalendarObject(args.calendar, args.uid);
614
- const truncated = truncateRecurrenceIcs(rawObj.data, occurrenceDate, existing.all_day);
650
+ const truncated = truncateRecurrenceIcs(rawObj.data, occurrenceDate, existing.allDay);
615
651
  // Nothing would remain: the cut is at or before the first occurrence,
616
652
  // so this is a whole-series delete and is treated as one.
617
653
  if (truncated === null) {
@@ -641,17 +677,20 @@ export const CALENDAR_TOOLS = [
641
677
  if (span === "this") {
642
678
  return run(async () => {
643
679
  const { event: existing, meta: eventMeta } = await service.getEventWithMeta(args.calendar, args.uid);
644
- if (existing.is_recurring) {
645
- if (!args.occurrence_date) {
646
- return calFail("validation_error", "occurrence_date is required when span is 'this' on a recurring event");
680
+ if (existing.isRecurring) {
681
+ if (!args.occurrenceDate) {
682
+ return calFail(ErrorCode.VALIDATION_FAILED, "occurrenceDate is required when span is 'this' on a recurring event");
647
683
  }
648
- const occurrenceDate = args.occurrence_date;
684
+ const occurrenceDate = args.occurrenceDate;
685
+ const invalidDate = checkOccurrenceDate(occurrenceDate);
686
+ if (invalidDate)
687
+ return invalidDate;
649
688
  const rawObj = await service.fetchRawCalendarObject(args.calendar, args.uid);
650
- let updatedIcs = addExdateToIcs(rawObj.data, occurrenceDate, existing.all_day);
689
+ let updatedIcs = addExdateToIcs(rawObj.data, occurrenceDate, existing.allDay);
651
690
  // Remove any existing exception VEVENT/VTODO for this occurrence,
652
691
  // matching by resolved instant (handles both UTC and TZID-form
653
692
  // RECURRENCE-ID) rather than a literal-text regex.
654
- updatedIcs = removeExceptionFromIcs(updatedIcs, occurrenceDate, existing.all_day);
693
+ updatedIcs = removeExceptionFromIcs(updatedIcs, occurrenceDate, existing.allDay);
655
694
  await service.updateEvent(args.calendar, args.uid, updatedIcs, {
656
695
  url: rawObj.url,
657
696
  etag: rawObj.etag,
@@ -699,7 +738,7 @@ export const CALENDAR_TOOLS = [
699
738
  title: { type: "string", description: "Event title" },
700
739
  start: { type: "string", description: "Start time (ISO 8601)" },
701
740
  end: { type: "string", description: "End time (ISO 8601)" },
702
- all_day: { type: "boolean", description: "All-day event flag (default: false)" },
741
+ allDay: { type: "boolean", description: "All-day event flag (default: false)" },
703
742
  location: { type: "string", description: "Event location" },
704
743
  description: { type: "string", description: "Event description" },
705
744
  attendees: ATTENDEES_PROP("List of attendee email addresses to invite."),
@@ -722,7 +761,7 @@ export const CALENDAR_TOOLS = [
722
761
  description: "Event reminders/alarms",
723
762
  },
724
763
  categories: CATEGORIES_PROP,
725
- recurrence_rule: {
764
+ recurrenceRule: {
726
765
  type: "string",
727
766
  description: "RFC 5545 RRULE string for a recurring event (e.g., 'FREQ=WEEKLY;BYDAY=MO'). FREQ is required.",
728
767
  },
@@ -757,8 +796,8 @@ export const CALENDAR_TOOLS = [
757
796
  }
758
797
  }
759
798
  catch (err) {
760
- if (err instanceof Error && err.message.startsWith("Invalid recurrence_rule:")) {
761
- return calFail("validation_error", err.message);
799
+ if (err instanceof IcsGenerateError) {
800
+ return calFail(ErrorCode.VALIDATION_FAILED, err.message);
762
801
  }
763
802
  throw err;
764
803
  }
@@ -779,15 +818,23 @@ export const CALENDAR_TOOLS = [
779
818
  type: "object",
780
819
  properties: {
781
820
  calendar: CALENDAR_PROP,
782
- ics_content: { type: "string", description: "Raw iCalendar content string" },
821
+ icsContent: { type: "string", description: "Raw iCalendar content string" },
783
822
  },
784
- required: ["calendar", "ics_content"],
823
+ required: ["calendar", "icsContent"],
785
824
  },
786
825
  outputSchema: importResultSchema,
787
826
  handler: (args, service) => run(async () => {
788
- const groups = splitIcsByUid(args.ics_content);
827
+ let groups;
828
+ try {
829
+ groups = splitIcsByUid(args.icsContent);
830
+ }
831
+ catch (err) {
832
+ if (err instanceof IcsParseError)
833
+ return calFail(ErrorCode.INVALID_ICS, err.message);
834
+ throw err;
835
+ }
789
836
  if (groups.length === 0) {
790
- return calFail("validation_error", "No events found in ICS content");
837
+ return calFail(ErrorCode.INVALID_ICS, "No events found in ICS content");
791
838
  }
792
839
  const importedEvents = [];
793
840
  const failed = [];
@@ -830,11 +877,11 @@ export const CALENDAR_TOOLS = [
830
877
  },
831
878
  start: { type: "string", description: "Start of range (ISO 8601)" },
832
879
  end: { type: "string", description: "End of range (ISO 8601)" },
833
- include_all_day_as_busy: {
880
+ includeAllDayAsBusy: {
834
881
  type: "boolean",
835
882
  description: "Treat all-day events as busy when computing from events (default: false). A server-side answer decides this itself.",
836
883
  },
837
- ignore_tentative: {
884
+ ignoreTentative: {
838
885
  type: "boolean",
839
886
  description: "If true, tentative periods are left out (default: false)",
840
887
  },
@@ -843,22 +890,20 @@ export const CALENDAR_TOOLS = [
843
890
  },
844
891
  outputSchema: freeBusySchema,
845
892
  handler: (args, service) => run(async () => {
846
- const startMs = new Date(args.start).getTime();
847
- const endMs = new Date(args.end).getTime();
848
- if (Number.isNaN(startMs) || Number.isNaN(endMs) || startMs >= endMs) {
849
- return calFail("validation_error", "start and end must be ISO 8601 with start before end");
850
- }
893
+ const invalid = checkRange(args.start, args.end);
894
+ if (invalid)
895
+ return invalid;
851
896
  let calendarIds = args.calendars;
852
897
  if (!calendarIds || calendarIds.length === 0) {
853
- calendarIds = (await service.listCalendars()).map((c) => c.calendar_id);
898
+ calendarIds = (await service.listCalendars()).map((c) => c.calendarId);
854
899
  }
855
900
  const { busy, sources } = await service.getFreeBusy(calendarIds, args.start, args.end, {
856
- includeAllDayAsBusy: args.include_all_day_as_busy ?? false,
857
- ignoreTentative: args.ignore_tentative ?? false,
901
+ includeAllDayAsBusy: args.includeAllDayAsBusy ?? false,
902
+ ignoreTentative: args.ignoreTentative ?? false,
858
903
  });
859
904
  return ok({
860
- start: new Date(startMs).toISOString(),
861
- end: new Date(endMs).toISOString(),
905
+ start: new Date(args.start).toISOString(),
906
+ end: new Date(args.end).toISOString(),
862
907
  busy,
863
908
  count: busy.length,
864
909
  sources,
@@ -881,24 +926,24 @@ export const CALENDAR_TOOLS = [
881
926
  start: { type: "string", description: "Start of search range (ISO 8601)" },
882
927
  end: { type: "string", description: "End of search range (ISO 8601)" },
883
928
  duration: { type: "number", description: "Minimum slot duration in minutes" },
884
- preferred_start: {
929
+ preferredStart: {
885
930
  type: "string",
886
931
  description: "Preferred earliest time (HH:MM, e.g., 08:00)",
887
932
  },
888
- preferred_end: {
933
+ preferredEnd: {
889
934
  type: "string",
890
935
  description: "Preferred latest time (HH:MM, e.g., 17:00)",
891
936
  },
892
- exclude_calendars: {
937
+ excludeCalendars: {
893
938
  type: "array",
894
939
  items: { type: "string", description: "Provider-prefixed calendar ID to exclude" },
895
940
  description: "Calendar IDs to exclude from busy time calculation",
896
941
  },
897
- include_all_day_as_busy: {
942
+ includeAllDayAsBusy: {
898
943
  type: "boolean",
899
944
  description: "Treat all-day events as busy (default: false)",
900
945
  },
901
- ignore_tentative: {
946
+ ignoreTentative: {
902
947
  type: "boolean",
903
948
  description: "If true, tentative events don't block slots (default: false)",
904
949
  },
@@ -907,17 +952,20 @@ export const CALENDAR_TOOLS = [
907
952
  },
908
953
  outputSchema: freeSlotsSchema,
909
954
  handler: (args, service) => run(async () => {
955
+ const invalid = checkRange(args.start, args.end);
956
+ if (invalid)
957
+ return invalid;
910
958
  let calendarIds = args.calendars;
911
959
  if (!calendarIds || calendarIds.length === 0) {
912
960
  const allCals = await service.listCalendars();
913
- calendarIds = allCals.map((c) => c.calendar_id);
961
+ calendarIds = allCals.map((c) => c.calendarId);
914
962
  }
915
963
  const slots = await service.findFreeSlots(calendarIds, args.start, args.end, args.duration, {
916
- preferredStart: args.preferred_start,
917
- preferredEnd: args.preferred_end,
918
- ignoreTentative: args.ignore_tentative ?? false,
919
- excludeCalendars: args.exclude_calendars,
920
- includeAllDayAsBusy: args.include_all_day_as_busy ?? false,
964
+ preferredStart: args.preferredStart,
965
+ preferredEnd: args.preferredEnd,
966
+ ignoreTentative: args.ignoreTentative ?? false,
967
+ excludeCalendars: args.excludeCalendars,
968
+ includeAllDayAsBusy: args.includeAllDayAsBusy ?? false,
921
969
  });
922
970
  return ok({ slots, count: slots.length });
923
971
  }),