Initial commit

packages/lib/src/eve/esi/calendar.ts

@@ -0,0 +1,113 @@
+/**
+ * EVE ESI Caldendar Module
+ *
+ * This module provides functions to interact with EVE Online's ESI Calendar API,
+ * allowing retrieval and management of calendar events for characters.
+ *
+ * ref: https://developers.eveonline.com/api-explorer#/operations/GetCharactersCharacterIdCalendar
+ */
+import { checkScopesAndGetCharacterId, esiFetch, type EsiOptions } from './util/fetch';
+import { tokenHasScopes } from '../oauth/eve-auth';
+import { ESI_SCOPE } from '../oauth';
+import { ESI_RATE_LIMIT_GROUP } from './util/rate-limits';
+
+export interface CalendarEvent {
+  event_date: string; // date-time string
+  event_id: number;
+  event_response: 'accepted' | 'declined' | 'tentative' | 'no_response';
+  importance: number;
+  title: string;
+}
+
+/**
+ * List calendar event summaries for a character.
+ *
+ * Get 50 event summaries from the calendar. If no from_event ID is given, the resource will
+ * return the next 50 chronological event summaries from now. If a from_event ID is
+ * specified, it will return the next 50 chronological event summaries from after that event
+ * - cached for 5 seconds
+ *
+ * @param options EsiOptions
+ * @param from_event Event from which to get the next 50 chronological event summaries
+ * @returns {Partial<CalendarEvent>[]}
+ */
+export async function listCalendarEventSummaries(options: EsiOptions, from_event?: number) {
+  const character_id = checkScopesAndGetCharacterId(options, ESI_SCOPE['esi-calendar.read_calendar_events.v1']);
+  return await esiFetch<Partial<CalendarEvent>[]>(`/characters/${character_id}/calendar/${from_event ?? '?from_event=' + from_event}`, {
+    ...options,
+    rateLimitGroup: ESI_RATE_LIMIT_GROUP.CHAR_SOCIAL,
+  });
+}
+
+export interface CalendarEventDetails {
+  date: string; // date-time string
+  duration: number; // in minutes
+  event_id: number;
+  importance: number;
+  owner_id: number;
+  owner_name: string;
+  owner_type: 'eve_server' | 'corporation' | 'faction' | 'alliance' | 'character';
+  response: 'accepted' | 'declined' | 'tentative' | 'no_response';
+  text: string;
+  title: string;
+}
+
+/**
+ * Get an event's details by its ID.
+ *
+ * Get all the information for a specific event.
+ *  - cached for 5 seconds
+ *
+ * @param options EsiOptions
+ * @param event_id Event Id
+ * @returns {Partial<CalendarEventDetails>}
+ */
+export async function getEventDetails(options: EsiOptions, event_id: number) {
+  const character_id = checkScopesAndGetCharacterId(options, ESI_SCOPE['esi-calendar.read_calendar_events.v1']);
+  return await esiFetch<Partial<CalendarEventDetails>>(`/characters/${character_id}/calendar/${event_id}/`, {
+    ...options,
+    rateLimitGroup: ESI_RATE_LIMIT_GROUP.CHAR_SOCIAL,
+  });
+}
+
+/**
+ * Respond to a calendar event.
+ *
+ * Accept, decline, or tentatively accept an event invitation.
+ *
+ * @param options EsiOptions
+ * @param event_id Event Id
+ * @param response Response: 'accepted' | 'declined' | 'tentative'
+ */
+export async function respondToEvent(options: EsiOptions, event_id: number, response: 'accepted' | 'declined' | 'tentative') {
+  const character_id = checkScopesAndGetCharacterId(options, ESI_SCOPE['esi-calendar.respond_calendar_events.v1']);
+  return await esiFetch<void>(`/characters/${character_id}/calendar/${event_id}/`, {
+    ...options,
+    method: 'PUT',
+    body: JSON.stringify({ response }),
+    rateLimitGroup: ESI_RATE_LIMIT_GROUP.CHAR_SOCIAL,
+  });
+}
+
+export interface CalendarEventAttendee {
+  character_id: number;
+  event_response: 'accepted' | 'declined' | 'tentative' | 'no_response';
+}
+
+/**
+ * Get the attendees of a calendar event.
+ *
+ * Get the list of attendees for a specific event.
+ *  - cached for 5 seconds
+ *
+ * @param options EsiOptions
+ * @param event_id Event Id
+ * @returns {Partial<CalendarEventAttendee>[]}
+ */
+export async function getEventAttendees(options: EsiOptions, event_id: number) {
+  const character_id = checkScopesAndGetCharacterId(options, ESI_SCOPE['esi-calendar.read_calendar_events.v1']);
+  return await esiFetch<Partial<CalendarEventAttendee>[]>(`/characters/${character_id}/calendar/${event_id}/attendees/`, {
+    ...options,
+    rateLimitGroup: ESI_RATE_LIMIT_GROUP.CHAR_SOCIAL,
+  });
+}