@symbiote-native/calendar 0.1.0

package/src/core/native-module.ts

@@ -0,0 +1,212 @@
+import { requireNativeModule } from 'expo-modules-core';
+import type { PermissionResponse } from 'expo-modules-core';
+import type {
+  IDialogEventResult,
+  IOpenEventPresentationOptions,
+  IPresentationOptions,
+  IRecurringEventOptions,
+  ISource,
+} from './types';
+
+const EXPO_CALENDAR_NEXT_MODULE_NAME = 'CalendarNext';
+
+// Each class is a real native SharedObject (Kotlin/Swift `Class(...)` registration) - `declare
+// class`, matching @symbiote-native/file-system's next/native-module.ts (see its own comment
+// for why a plain object type with a `new(...)` signature does not work the same way).
+export declare class NativeExpoCalendar {
+  readonly id: string;
+  readonly title: string;
+  /** @platform android */
+  readonly name?: string | null;
+  readonly source?: ISource;
+  /** @platform ios */
+  readonly sourceId?: string;
+  /** @platform ios */
+  readonly type?: string;
+  readonly color?: string;
+  /** @platform ios */
+  readonly entityType?: string;
+  readonly allowsModifications: boolean;
+  readonly allowedAvailabilities: string[];
+  /** @platform android */
+  readonly isVisible?: boolean;
+  /** @platform android */
+  readonly isSynced?: boolean;
+  /** @platform android */
+  readonly timeZone?: string;
+  /** @platform android */
+  readonly isPrimary?: boolean;
+  /** @platform android */
+  readonly allowedReminders?: string[];
+  /** @platform android */
+  readonly allowedAttendeeTypes?: string[];
+  /** @platform android */
+  readonly ownerAccount?: string;
+  /** @platform android */
+  readonly accessLevel?: string;
+
+  listEvents(
+    startDate: string | Date,
+    endDate: string | Date,
+  ): Promise<NativeExpoCalendarEvent[]>;
+  /** @platform ios - typed as always-present, guarded at runtime. */
+  listReminders(
+    startDate: string | Date | null,
+    endDate: string | Date | null,
+    status: string | null,
+  ): Promise<NativeExpoCalendarReminder[]>;
+  createEvent(
+    record: Record<string, unknown>,
+  ): Promise<NativeExpoCalendarEvent>;
+  /** @platform ios - typed as always-present, guarded at runtime. */
+  createReminder(
+    record: Record<string, unknown>,
+  ): Promise<NativeExpoCalendarReminder>;
+  addEventWithForm(
+    options?: Record<string, unknown>,
+  ): Promise<IDialogEventResult>;
+  update(patch: Record<string, unknown>): Promise<void>;
+  delete(): Promise<void>;
+}
+
+export declare class NativeExpoCalendarEvent {
+  readonly id: string;
+  readonly calendarId?: string;
+  readonly title?: string;
+  readonly location?: string;
+  /** @platform ios */
+  readonly creationDate?: string;
+  /** @platform ios */
+  readonly lastModifiedDate?: string;
+  readonly timeZone?: string;
+  /** @platform android */
+  readonly endTimeZone?: string;
+  /** @platform ios */
+  readonly url?: string;
+  readonly notes?: string;
+  readonly alarms?: unknown[];
+  readonly recurrenceRule?: Record<string, unknown> | null;
+  readonly startDate?: string;
+  readonly endDate?: string;
+  /** @platform ios */
+  readonly originalStartDate?: string;
+  /** @platform ios */
+  readonly isDetached?: boolean;
+  readonly allDay: boolean;
+  readonly availability?: string;
+  readonly status?: string;
+  /** @platform ios */
+  readonly organizer?: Record<string, unknown>;
+  /** @platform android */
+  readonly organizerEmail?: string;
+  /** @platform android */
+  readonly accessLevel?: string;
+  /** @platform android */
+  readonly guestsCanModify?: boolean;
+  /** @platform android */
+  readonly guestsCanInviteOthers?: boolean;
+  /** @platform android */
+  readonly guestsCanSeeGuests?: boolean;
+  /** @platform android */
+  readonly originalId?: string;
+  /** @platform android */
+  readonly instanceId?: string;
+
+  /** @platform android - typed as always-present, guarded at runtime. */
+  createAttendee(
+    record: Record<string, unknown>,
+  ): Promise<NativeExpoCalendarAttendee>;
+  openInCalendar(
+    options?: IOpenEventPresentationOptions | null,
+  ): Promise<IDialogEventResult>;
+  editInCalendar(
+    options?: IPresentationOptions | null,
+  ): Promise<IDialogEventResult>;
+  getOccurrenceSync(options?: IRecurringEventOptions): NativeExpoCalendarEvent;
+  getAttendees(): Promise<NativeExpoCalendarAttendee[]>;
+  update(
+    patch: Record<string, unknown>,
+    nullableFields: string[],
+  ): Promise<void>;
+  delete(): Promise<void>;
+}
+
+/** @platform android - iOS registers this class with no properties or methods. */
+export declare class NativeExpoCalendarAttendee {
+  constructor(record: Record<string, unknown>);
+  readonly id?: string;
+  readonly name?: string;
+  readonly role?: string;
+  readonly status?: string;
+  readonly type?: string;
+  readonly email?: string;
+
+  update(
+    patch: Record<string, unknown>,
+    nullableFields: string[],
+  ): Promise<void>;
+  delete(): Promise<void>;
+}
+
+/** @platform ios - Android registers this class with no properties or methods. */
+export declare class NativeExpoCalendarReminder {
+  constructor(id: string);
+  readonly id?: string;
+  readonly calendarId?: string;
+  readonly title?: string;
+  readonly location?: string;
+  readonly creationDate?: string;
+  readonly lastModifiedDate?: string;
+  readonly timeZone?: string;
+  readonly url?: string;
+  readonly notes?: string;
+  readonly alarms?: unknown[];
+  readonly recurrenceRule?: Record<string, unknown> | null;
+  readonly allDay: boolean;
+  readonly startDate?: string;
+  readonly dueDate?: string;
+  readonly completed: boolean;
+  readonly completionDate?: string;
+
+  update(
+    patch: Record<string, unknown>,
+    nullableFields: string[],
+  ): Promise<void>;
+  delete(): Promise<void>;
+}
+
+export type INativeCalendarNextModule = {
+  ExpoCalendar: typeof NativeExpoCalendar;
+  ExpoCalendarEvent: typeof NativeExpoCalendarEvent;
+  ExpoCalendarAttendee: typeof NativeExpoCalendarAttendee;
+  ExpoCalendarReminder: typeof NativeExpoCalendarReminder;
+
+  getCalendars(type: string | null): Promise<NativeExpoCalendar[]>;
+  getCalendarById(id: string): Promise<NativeExpoCalendar>;
+  createCalendar(record: Record<string, unknown>): Promise<NativeExpoCalendar>;
+  listEvents(
+    calendarIds: string[],
+    startDate: string,
+    endDate: string,
+  ): Promise<NativeExpoCalendarEvent[]>;
+  getEventById(id: string): Promise<NativeExpoCalendarEvent>;
+  getCalendarPermissions(writeOnly?: boolean): Promise<PermissionResponse>;
+  requestCalendarPermissions(writeOnly?: boolean): Promise<PermissionResponse>;
+
+  /** @platform ios */
+  getDefaultCalendarSync?(): NativeExpoCalendar;
+  /** @platform ios */
+  presentPicker?(): Promise<NativeExpoCalendar | null>;
+  /** @platform ios */
+  getReminderById?(id: string): Promise<NativeExpoCalendarReminder>;
+  /** @platform ios */
+  getRemindersPermissions?(): Promise<PermissionResponse>;
+  /** @platform ios */
+  requestRemindersPermissions?(): Promise<PermissionResponse>;
+  /** @platform ios */
+  getSourcesSync?(): ISource[];
+};
+
+export const expoCalendarNext = requireNativeModule<INativeCalendarNextModule>(
+  EXPO_CALENDAR_NEXT_MODULE_NAME,
+);

package/src/core/reminder.ts

@@ -0,0 +1,52 @@
+import { Platform, UnavailabilityError } from 'expo-modules-core';
+import { expoCalendarNext } from './native-module';
+import type { NativeExpoCalendarReminder } from './native-module';
+import type { IReminderPatch } from './types';
+import { getNullableDetailsFields, stringifyDateValues } from './utils';
+
+/** @platform ios - Android registers this class with no properties or methods. */
+export class ExpoCalendarReminder
+  extends expoCalendarNext.ExpoCalendarReminder
+{
+  override async update(details: IReminderPatch): Promise<void> {
+    if (Platform.OS !== 'ios') {
+      throw new UnavailabilityError('ExpoCalendarReminder', 'update');
+    }
+    return super.update(
+      stringifyDateValues(details),
+      getNullableDetailsFields(details),
+    );
+  }
+
+  override async delete(): Promise<void> {
+    if (Platform.OS !== 'ios') {
+      throw new UnavailabilityError('ExpoCalendarReminder', 'delete');
+    }
+    return super.delete();
+  }
+
+  static async get(reminderId: string): Promise<ExpoCalendarReminder> {
+    if (Platform.OS !== 'ios' || !expoCalendarNext.getReminderById) {
+      throw new UnavailabilityError('ExpoCalendarReminder', 'get');
+    }
+    return upgradeToExpoCalendarReminder(
+      await expoCalendarNext.getReminderById(reminderId),
+    );
+  }
+}
+
+function isExpoCalendarReminder(value: unknown): value is ExpoCalendarReminder {
+  return value instanceof ExpoCalendarReminder;
+}
+
+export function upgradeToExpoCalendarReminder(
+  native: NativeExpoCalendarReminder,
+): ExpoCalendarReminder {
+  Object.setPrototypeOf(native, ExpoCalendarReminder.prototype);
+  if (!isExpoCalendarReminder(native)) {
+    throw new Error(
+      'unreachable - just reassigned the prototype to ExpoCalendarReminder',
+    );
+  }
+  return native;
+}

package/src/core/types.ts

@@ -0,0 +1,209 @@
+import type {
+  AlarmMethod,
+  AttendeeRole,
+  AttendeeStatus,
+  AttendeeType,
+  CalendarAccessLevel,
+  CalendarDialogResultActions,
+  DayOfTheWeek,
+  Frequency,
+  MonthOfTheYear,
+} from './enums';
+
+export type ISource = {
+  id?: string;
+  type?: string;
+  name?: string;
+  isLocalAccount?: boolean;
+};
+
+export type IDaysOfTheWeek = {
+  dayOfTheWeek: DayOfTheWeek;
+  /** `-53` to `53`; `0` ignores this field. */
+  weekNumber?: number;
+};
+
+export type IRecurrenceRule = {
+  frequency: Frequency;
+  /** @default 1 */
+  interval?: number;
+  endDate?: string | Date | null;
+  occurrence?: number | null;
+  /** @platform ios */
+  daysOfTheWeek?: IDaysOfTheWeek[] | null;
+  /** @platform ios */
+  daysOfTheMonth?: number[] | null;
+  /** @platform ios */
+  monthsOfTheYear?: MonthOfTheYear[] | null;
+  /** @platform ios */
+  weeksOfTheYear?: number[] | null;
+  /** @platform ios */
+  daysOfTheYear?: number[] | null;
+  /** @platform ios */
+  setPositions?: number[] | null;
+};
+
+export type IAlarmLocation = {
+  title?: string;
+  proximity?: string;
+  radius?: number;
+  coords?: { latitude?: number; longitude?: number };
+};
+
+export type IAlarm = {
+  /** @platform ios */
+  absoluteDate?: string;
+  relativeOffset?: number;
+  structuredLocation?: IAlarmLocation;
+  /** @platform android */
+  method?: AlarmMethod;
+};
+
+/** Fields for `createCalendar()` - all optional, matches upstream's `Partial<Calendar>`. */
+export type ICalendarInput = {
+  title?: string;
+  /** @platform android */
+  name?: string;
+  source?: ISource;
+  color?: string;
+  /** @platform android */
+  isVisible?: boolean;
+  /** @platform android */
+  isSynced?: boolean;
+  /** @platform android */
+  timeZone?: string;
+  /** @platform android */
+  isPrimary?: boolean;
+  allowedAvailabilities?: string[];
+  /** @platform android */
+  allowedReminders?: AlarmMethod[];
+  /** @platform android */
+  allowedAttendeeTypes?: AttendeeType[];
+  /** @platform android */
+  ownerAccount?: string;
+  /** @platform android */
+  accessLevel?: CalendarAccessLevel;
+  /** @platform ios */
+  sourceId?: string;
+};
+
+/** Fields for `calendar.update()`; a field set to `null` clears it natively. */
+export type ICalendarPatch = {
+  title?: string | null;
+  /** @platform android */
+  name?: string | null;
+  color?: string | null;
+  /** @platform android */
+  isVisible?: boolean | null;
+  /** @platform android */
+  isSynced?: boolean | null;
+  /** @platform android */
+  timeZone?: string | null;
+};
+
+/** Fields for `calendar.createEvent()` - all optional, matches upstream's `Omit<Partial<...>>`. */
+export type IEventInput = {
+  startDate?: string | Date;
+  endDate?: string | Date;
+  title?: string;
+  location?: string;
+  timeZone?: string;
+  /** @platform android */
+  endTimeZone?: string;
+  notes?: string;
+  alarms?: IAlarm[];
+  recurrenceRule?: IRecurrenceRule;
+  allDay?: boolean;
+  availability?: string;
+  /** @platform android */
+  status?: string;
+  /** @platform android */
+  organizerEmail?: string;
+  /** @platform android */
+  accessLevel?: string;
+  /** @platform android */
+  guestsCanModify?: boolean;
+  /** @platform android */
+  guestsCanInviteOthers?: boolean;
+  /** @platform android */
+  guestsCanSeeGuests?: boolean;
+};
+
+/** Fields for `event.update()`; a field set to `null` clears it natively. */
+export type IEventPatch = Partial<{
+  [K in keyof IEventInput]: IEventInput[K] | null;
+}>;
+
+/** Fields for `event.createAttendee()`. @platform android */
+export type IAttendeeInput = {
+  name: string;
+  role: AttendeeRole;
+  status: AttendeeStatus;
+  type: AttendeeType;
+  email: string;
+};
+
+/** Fields for `attendee.update()`. @platform android */
+export type IAttendeePatch = Partial<{
+  [K in keyof IAttendeeInput]: IAttendeeInput[K] | null;
+}>;
+
+/** Fields for `calendar.createReminder()`. @platform ios */
+export type IReminderInput = {
+  title?: string;
+  location?: string;
+  notes?: string;
+  startDate?: string | Date;
+  dueDate?: string | Date;
+  completionDate?: string | Date;
+  timeZone?: string;
+  alarms?: IAlarm[];
+  recurrenceRule?: IRecurrenceRule;
+  url?: string;
+  allDay?: boolean;
+  completed?: boolean;
+};
+
+/** Fields for `reminder.update()`; a field set to `null` clears it natively. @platform ios */
+export type IReminderPatch = Partial<{
+  [K in keyof IReminderInput]: IReminderInput[K] | null;
+}>;
+
+export type IRecurringEventOptions = {
+  /** Applies to `instanceStartDate` and every future occurrence when `true`. */
+  futureEvents?: boolean;
+  instanceStartDate?: string | Date;
+};
+
+export type IPresentationOptions = {
+  /** `true` resolves `'done'` right after opening. @default true @platform android */
+  startNewActivityTask?: boolean;
+};
+
+export type IOpenEventPresentationOptions = IPresentationOptions & {
+  /** @default false @platform ios */
+  allowsEditing?: boolean;
+  /** @default false @platform ios */
+  allowsCalendarPreview?: boolean;
+};
+
+/** Fields for `calendar.addEventWithForm()`. */
+export type IAddEventWithFormOptions = {
+  title?: string;
+  location?: string;
+  notes?: string;
+  url?: string;
+  /** @platform android */
+  timeZone?: string;
+  availability?: string;
+  allDay?: boolean;
+  startDate?: string | Date;
+  endDate?: string | Date;
+  recurrenceRule?: IRecurrenceRule;
+  alarms?: IAlarm[];
+} & IPresentationOptions;
+
+export type IDialogEventResult = {
+  action: CalendarDialogResultActions;
+  id?: string | null;
+};

package/src/core/utils.ts

@@ -0,0 +1,39 @@
+export function stringifyIfDate(value: Date): string;
+export function stringifyIfDate(value: unknown): unknown;
+export function stringifyIfDate(value: unknown): unknown {
+  return value instanceof Date ? value.toISOString() : value;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    !Array.isArray(value) &&
+    !(value instanceof Date)
+  );
+}
+
+function stringifyValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(stringifyValue);
+  if (isPlainObject(value)) return stringifyDateValues(value);
+  return stringifyIfDate(value);
+}
+
+/** Recursively converts every `Date` field of `obj` to an ISO string for the native bridge. */
+export function stringifyDateValues(
+  obj: Record<string, unknown>,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(obj)) {
+    result[key] = stringifyValue(value);
+  }
+  return result;
+}
+
+/** `null` in a patch means "clear natively" - the native `update()` needs the field named
+ * separately, in addition to staying in the stringified record with its `null` value. */
+export function getNullableDetailsFields(
+  details: Record<string, unknown>,
+): string[] {
+  return Object.keys(details).filter(key => details[key] === null);
+}