@symbiote-native/calendar 0.1.0

package/src/angular/services/reminders-permissions.service/index.ts

@@ -0,0 +1,16 @@
+// Angular twin of `../../react`'s `useRemindersPermissions`
+
+import { Injectable } from '@angular/core';
+import { PermissionsServiceBase } from '@symbiote-native/angular';
+import {
+  getRemindersPermissions,
+  requestRemindersPermissions,
+} from '../../../core/calendar';
+import type { PermissionResponse } from 'expo-modules-core';
+
+@Injectable({ providedIn: 'root' })
+export class RemindersPermissionsService extends PermissionsServiceBase<PermissionResponse> {
+  constructor() {
+    super(getRemindersPermissions, requestRemindersPermissions);
+  }
+}

package/src/core/attendee.ts

@@ -0,0 +1,43 @@
+import { UnavailabilityError } from 'expo-modules-core';
+import { expoCalendarNext } from './native-module';
+import type { NativeExpoCalendarAttendee } from './native-module';
+import type { IAttendeePatch } from './types';
+import { getNullableDetailsFields, stringifyDateValues } from './utils';
+
+/** @platform android - iOS registers this class with no properties or methods. */
+export class ExpoCalendarAttendee
+  extends expoCalendarNext.ExpoCalendarAttendee
+{
+  override async update(details: IAttendeePatch): Promise<void> {
+    if (!super.update) {
+      throw new UnavailabilityError('ExpoCalendarAttendee', 'update');
+    }
+    return super.update(
+      stringifyDateValues(details),
+      getNullableDetailsFields(details),
+    );
+  }
+
+  override async delete(): Promise<void> {
+    if (!super.delete) {
+      throw new UnavailabilityError('ExpoCalendarAttendee', 'delete');
+    }
+    return super.delete();
+  }
+}
+
+function isExpoCalendarAttendee(value: unknown): value is ExpoCalendarAttendee {
+  return value instanceof ExpoCalendarAttendee;
+}
+
+export function upgradeToExpoCalendarAttendee(
+  native: NativeExpoCalendarAttendee,
+): ExpoCalendarAttendee {
+  Object.setPrototypeOf(native, ExpoCalendarAttendee.prototype);
+  if (!isExpoCalendarAttendee(native)) {
+    throw new Error(
+      'unreachable - just reassigned the prototype to ExpoCalendarAttendee',
+    );
+  }
+  return native;
+}

package/src/core/calendar-permission-api.ts

@@ -0,0 +1,16 @@
+// `methods` every adapter's `useCalendarPermissions` binds to the shared
+// `@symbiote-native/{react,vue,solid,svelte}` `createPermissionHook` factory
+
+import { getCalendarPermissions, requestCalendarPermissions } from './calendar';
+import { splitWriteOnlyPermissionOptions } from '@symbiote-native/engine';
+
+export type ICalendarPermissionMethodOptions = { writeOnly?: boolean };
+
+export const calendarPermissionMethods = {
+  getMethod: (options?: ICalendarPermissionMethodOptions) =>
+    getCalendarPermissions(options?.writeOnly),
+  requestMethod: (options?: ICalendarPermissionMethodOptions) =>
+    requestCalendarPermissions(options?.writeOnly),
+};
+
+export const splitCalendarPermissionOptions = splitWriteOnlyPermissionOptions;

package/src/core/calendar.ts

@@ -0,0 +1,197 @@
+import { UnavailabilityError } from 'expo-modules-core';
+import type { PermissionResponse } from 'expo-modules-core';
+import { expoCalendarNext } from './native-module';
+import type { NativeExpoCalendar } from './native-module';
+import type {
+  IAddEventWithFormOptions,
+  ICalendarInput,
+  ICalendarPatch,
+  IDialogEventResult,
+  IEventInput,
+  IReminderInput,
+  ISource,
+} from './types';
+import type { EntityTypes } from './enums';
+import { stringifyDateValues, stringifyIfDate } from './utils';
+import { ExpoCalendarEvent, upgradeToExpoCalendarEvent } from './event';
+import {
+  ExpoCalendarReminder,
+  upgradeToExpoCalendarReminder,
+} from './reminder';
+
+export class ExpoCalendar extends expoCalendarNext.ExpoCalendar {
+  override async createEvent(details: IEventInput): Promise<ExpoCalendarEvent> {
+    return upgradeToExpoCalendarEvent(
+      await super.createEvent(stringifyDateValues(details)),
+    );
+  }
+
+  /** @platform ios */
+  override async createReminder(
+    details: IReminderInput,
+  ): Promise<ExpoCalendarReminder> {
+    if (!super.createReminder) {
+      throw new UnavailabilityError('ExpoCalendar', 'createReminder');
+    }
+    return upgradeToExpoCalendarReminder(
+      await super.createReminder(stringifyDateValues(details)),
+    );
+  }
+
+  override async listEvents(
+    startDate: Date,
+    endDate: Date,
+  ): Promise<ExpoCalendarEvent[]> {
+    if (!startDate) {
+      throw new Error(
+        'listEvents must be called with a startDate (date) to search for events',
+      );
+    }
+    if (!endDate) {
+      throw new Error(
+        'listEvents must be called with an endDate (date) to search for events',
+      );
+    }
+    const events = await super.listEvents(
+      stringifyIfDate(startDate),
+      stringifyIfDate(endDate),
+    );
+    return events.map(upgradeToExpoCalendarEvent);
+  }
+
+  /** @platform ios */
+  override async listReminders(
+    startDate: string | Date | null = null,
+    endDate: string | Date | null = null,
+    status: string | null = null,
+  ): Promise<ExpoCalendarReminder[]> {
+    if (!super.listReminders) {
+      throw new UnavailabilityError('ExpoCalendar', 'listReminders');
+    }
+    const reminders = await super.listReminders(startDate, endDate, status);
+    return reminders.map(upgradeToExpoCalendarReminder);
+  }
+
+  override async update(details: ICalendarPatch): Promise<void> {
+    return super.update(stringifyDateValues(details));
+  }
+
+  override async addEventWithForm(
+    options?: IAddEventWithFormOptions,
+  ): Promise<IDialogEventResult> {
+    if (!super.addEventWithForm) {
+      throw new UnavailabilityError('ExpoCalendar', 'addEventWithForm');
+    }
+    return super.addEventWithForm(options && stringifyDateValues(options));
+  }
+
+  override async delete(): Promise<void> {
+    return super.delete();
+  }
+
+  static async get(calendarId: string): Promise<ExpoCalendar> {
+    return upgradeToExpoCalendar(
+      await expoCalendarNext.getCalendarById(calendarId),
+    );
+  }
+}
+
+function isExpoCalendar(value: unknown): value is ExpoCalendar {
+  return value instanceof ExpoCalendar;
+}
+
+function upgradeToExpoCalendar(native: NativeExpoCalendar): ExpoCalendar {
+  Object.setPrototypeOf(native, ExpoCalendar.prototype);
+  if (!isExpoCalendar(native)) {
+    throw new Error(
+      'unreachable - just reassigned the prototype to ExpoCalendar',
+    );
+  }
+  return native;
+}
+
+/** @platform ios - Android has no single system-managed default calendar. */
+export function getDefaultCalendarSync(): ExpoCalendar {
+  if (!expoCalendarNext.getDefaultCalendarSync) {
+    throw new UnavailabilityError('Calendar', 'getDefaultCalendarSync');
+  }
+  return upgradeToExpoCalendar(expoCalendarNext.getDefaultCalendarSync());
+}
+
+export async function getCalendars(
+  entityType?: EntityTypes,
+): Promise<ExpoCalendar[]> {
+  if (!expoCalendarNext.getCalendars) {
+    throw new UnavailabilityError('Calendar', 'getCalendars');
+  }
+  const calendars = await expoCalendarNext.getCalendars(entityType ?? null);
+  return calendars.map(upgradeToExpoCalendar);
+}
+
+export async function createCalendar(
+  details: ICalendarInput = {},
+): Promise<ExpoCalendar> {
+  return upgradeToExpoCalendar(await expoCalendarNext.createCalendar(details));
+}
+
+/** @platform ios */
+export async function presentPicker(): Promise<ExpoCalendar | null> {
+  if (!expoCalendarNext.presentPicker) {
+    throw new UnavailabilityError('Calendar', 'presentPicker');
+  }
+  const calendar = await expoCalendarNext.presentPicker();
+  return calendar ? upgradeToExpoCalendar(calendar) : null;
+}
+
+/** Searches events across several calendars at once - use `calendar.listEvents()` for one. */
+export async function listEvents(
+  calendars: (string | ExpoCalendar)[],
+  startDate: Date,
+  endDate: Date,
+): Promise<ExpoCalendarEvent[]> {
+  const calendarIds = calendars.map(calendar =>
+    typeof calendar === 'string' ? calendar : calendar.id,
+  );
+  const events = await expoCalendarNext.listEvents(
+    calendarIds,
+    stringifyIfDate(startDate),
+    stringifyIfDate(endDate),
+  );
+  return events.map(upgradeToExpoCalendarEvent);
+}
+
+export async function requestCalendarPermissions(
+  writeOnly?: boolean,
+): Promise<PermissionResponse> {
+  return expoCalendarNext.requestCalendarPermissions(writeOnly);
+}
+
+export async function getCalendarPermissions(
+  writeOnly?: boolean,
+): Promise<PermissionResponse> {
+  return expoCalendarNext.getCalendarPermissions(writeOnly);
+}
+
+/** @platform ios */
+export async function requestRemindersPermissions(): Promise<PermissionResponse> {
+  if (!expoCalendarNext.requestRemindersPermissions) {
+    throw new UnavailabilityError('Calendar', 'requestRemindersPermissions');
+  }
+  return expoCalendarNext.requestRemindersPermissions();
+}
+
+/** @platform ios */
+export async function getRemindersPermissions(): Promise<PermissionResponse> {
+  if (!expoCalendarNext.getRemindersPermissions) {
+    throw new UnavailabilityError('Calendar', 'getRemindersPermissions');
+  }
+  return expoCalendarNext.getRemindersPermissions();
+}
+
+/** @platform ios - Android has no first-class calendar-sources API. */
+export function getSourcesSync(): ISource[] {
+  if (!expoCalendarNext.getSourcesSync) {
+    throw new UnavailabilityError('Calendar', 'getSourcesSync');
+  }
+  return expoCalendarNext.getSourcesSync();
+}

package/src/core/enums.ts

@@ -0,0 +1,156 @@
+export enum EntityTypes {
+  EVENT = 'event',
+  REMINDER = 'reminder',
+}
+
+export enum Frequency {
+  DAILY = 'daily',
+  WEEKLY = 'weekly',
+  MONTHLY = 'monthly',
+  YEARLY = 'yearly',
+}
+
+/** `NOT_SUPPORTED`/`UNAVAILABLE` are iOS-only. */
+export enum Availability {
+  NOT_SUPPORTED = 'notSupported',
+  BUSY = 'busy',
+  FREE = 'free',
+  TENTATIVE = 'tentative',
+  UNAVAILABLE = 'unavailable',
+}
+
+/** @platform ios */
+export enum CalendarType {
+  LOCAL = 'local',
+  CALDAV = 'caldav',
+  EXCHANGE = 'exchange',
+  SUBSCRIBED = 'subscribed',
+  BIRTHDAYS = 'birthdays',
+  UNKNOWN = 'unknown',
+}
+
+export enum EventStatus {
+  NONE = 'none',
+  CONFIRMED = 'confirmed',
+  TENTATIVE = 'tentative',
+  CANCELED = 'canceled',
+}
+
+/** @platform ios */
+export enum SourceType {
+  LOCAL = 'local',
+  EXCHANGE = 'exchange',
+  CALDAV = 'caldav',
+  MOBILEME = 'mobileme',
+  SUBSCRIBED = 'subscribed',
+  BIRTHDAYS = 'birthdays',
+}
+
+/** iOS: UNKNOWN/REQUIRED/OPTIONAL/CHAIR/NON_PARTICIPANT. Android: the rest. */
+export enum AttendeeRole {
+  UNKNOWN = 'unknown',
+  REQUIRED = 'required',
+  OPTIONAL = 'optional',
+  CHAIR = 'chair',
+  NON_PARTICIPANT = 'nonParticipant',
+  ATTENDEE = 'attendee',
+  ORGANIZER = 'organizer',
+  PERFORMER = 'performer',
+  SPEAKER = 'speaker',
+  NONE = 'none',
+}
+
+/** iOS: UNKNOWN/PENDING/DELEGATED/COMPLETED/IN_PROCESS. Android: INVITED/NONE. */
+export enum AttendeeStatus {
+  UNKNOWN = 'unknown',
+  PENDING = 'pending',
+  ACCEPTED = 'accepted',
+  DECLINED = 'declined',
+  TENTATIVE = 'tentative',
+  DELEGATED = 'delegated',
+  COMPLETED = 'completed',
+  IN_PROCESS = 'inProcess',
+  INVITED = 'invited',
+  NONE = 'none',
+}
+
+/** iOS: UNKNOWN/PERSON/ROOM/GROUP. Android: OPTIONAL/REQUIRED/NONE. Both: RESOURCE. */
+export enum AttendeeType {
+  UNKNOWN = 'unknown',
+  PERSON = 'person',
+  ROOM = 'room',
+  GROUP = 'group',
+  RESOURCE = 'resource',
+  OPTIONAL = 'optional',
+  REQUIRED = 'required',
+  NONE = 'none',
+}
+
+/** @platform android */
+export enum AlarmMethod {
+  ALARM = 'alarm',
+  ALERT = 'alert',
+  EMAIL = 'email',
+  SMS = 'sms',
+  DEFAULT = 'default',
+}
+
+/** @platform android */
+export enum EventAccessLevel {
+  CONFIDENTIAL = 'confidential',
+  PRIVATE = 'private',
+  PUBLIC = 'public',
+  DEFAULT = 'default',
+}
+
+/** @platform android */
+export enum CalendarAccessLevel {
+  CONTRIBUTOR = 'contributor',
+  EDITOR = 'editor',
+  FREEBUSY = 'freebusy',
+  OVERRIDE = 'override',
+  OWNER = 'owner',
+  READ = 'read',
+  RESPOND = 'respond',
+  ROOT = 'root',
+  NONE = 'none',
+}
+
+/** @platform ios */
+export enum ReminderStatus {
+  COMPLETED = 'completed',
+  INCOMPLETE = 'incomplete',
+}
+
+export enum DayOfTheWeek {
+  Sunday = 1,
+  Monday = 2,
+  Tuesday = 3,
+  Wednesday = 4,
+  Thursday = 5,
+  Friday = 6,
+  Saturday = 7,
+}
+
+export enum MonthOfTheYear {
+  January = 1,
+  February = 2,
+  March = 3,
+  April = 4,
+  May = 5,
+  June = 6,
+  July = 7,
+  August = 8,
+  September = 9,
+  October = 10,
+  November = 11,
+  December = 12,
+}
+
+export enum CalendarDialogResultActions {
+  done = 'done',
+  canceled = 'canceled',
+  deleted = 'deleted',
+  responded = 'responded',
+  saved = 'saved',
+}

package/src/core/event.ts

@@ -0,0 +1,70 @@
+import { UnavailabilityError } from 'expo-modules-core';
+import { expoCalendarNext } from './native-module';
+import type { NativeExpoCalendarEvent } from './native-module';
+import type {
+  IAttendeeInput,
+  IEventPatch,
+  IRecurringEventOptions,
+} from './types';
+import { getNullableDetailsFields, stringifyDateValues } from './utils';
+import {
+  ExpoCalendarAttendee,
+  upgradeToExpoCalendarAttendee,
+} from './attendee';
+
+export class ExpoCalendarEvent extends expoCalendarNext.ExpoCalendarEvent {
+  override getOccurrenceSync(
+    options: IRecurringEventOptions = {},
+  ): ExpoCalendarEvent {
+    const occurrence = super.getOccurrenceSync(stringifyDateValues(options));
+    return upgradeToExpoCalendarEvent(occurrence);
+  }
+
+  override async getAttendees(): Promise<ExpoCalendarAttendee[]> {
+    const attendees = await super.getAttendees();
+    return attendees.map(upgradeToExpoCalendarAttendee);
+  }
+
+  /** @platform android */
+  override async createAttendee(
+    attendee: IAttendeeInput,
+  ): Promise<ExpoCalendarAttendee> {
+    if (!super.createAttendee) {
+      throw new UnavailabilityError('ExpoCalendarEvent', 'createAttendee');
+    }
+    return upgradeToExpoCalendarAttendee(await super.createAttendee(attendee));
+  }
+
+  override async update(details: IEventPatch): Promise<void> {
+    return super.update(
+      stringifyDateValues(details),
+      getNullableDetailsFields(details),
+    );
+  }
+
+  override async delete(): Promise<void> {
+    return super.delete();
+  }
+
+  static async get(eventId: string): Promise<ExpoCalendarEvent> {
+    return upgradeToExpoCalendarEvent(
+      await expoCalendarNext.getEventById(eventId),
+    );
+  }
+}
+
+function isExpoCalendarEvent(value: unknown): value is ExpoCalendarEvent {
+  return value instanceof ExpoCalendarEvent;
+}
+
+export function upgradeToExpoCalendarEvent(
+  native: NativeExpoCalendarEvent,
+): ExpoCalendarEvent {
+  Object.setPrototypeOf(native, ExpoCalendarEvent.prototype);
+  if (!isExpoCalendarEvent(native)) {
+    throw new Error(
+      'unreachable - just reassigned the prototype to ExpoCalendarEvent',
+    );
+  }
+  return native;
+}

package/src/core/index.ts

@@ -0,0 +1,18 @@
+export * from './enums';
+export * from './types';
+export { ExpoCalendarEvent } from './event';
+export { ExpoCalendarAttendee } from './attendee';
+export { ExpoCalendarReminder } from './reminder';
+export {
+  ExpoCalendar,
+  getDefaultCalendarSync,
+  getCalendars,
+  createCalendar,
+  presentPicker,
+  listEvents,
+  requestCalendarPermissions,
+  getCalendarPermissions,
+  requestRemindersPermissions,
+  getRemindersPermissions,
+  getSourcesSync,
+} from './calendar';