refactor(types): breakdown definitions file (#164)

Add reminders access interface.
ebarooni · Feb 4, 2025 · aebab04 · aebab04
1 parent b9cdf97
commit aebab04
Show file tree

Hide file tree

Showing 3 changed files with 52 additions and 18 deletions.
diff --git a/src/definitions.ts b/src/definitions.ts
@@ -7,9 +7,12 @@ import type { CalendarSource } from "./schemas/interfaces/calendar-source";
 import { EventSpan } from "./schemas/enums/event-span";
 import type { Reminder } from "./schemas/interfaces/reminder";
 import type { ReminderRecurrenceRule } from "./schemas/interfaces/reminder-recurrence-rule";
+import { RemindersAccess } from "./sub-definitions/reminders-access";
 import type { RemindersList } from "./schemas/interfaces/reminders-list";
 
-export interface CapacitorCalendarPlugin extends CalendarAccess {
+export interface CapacitorCalendarPlugin
+  extends CalendarAccess,
+    RemindersAccess {
   /**
    * Creates an event in the calendar by using the native calendar.
    * On iOS opens a native sheet and on Android opens an intent.

diff --git a/src/sub-definitions/calendar-access.ts b/src/sub-definitions/calendar-access.ts
@@ -1,39 +1,42 @@
+import { CalendarPermissionScope } from "../schemas/enums/calendar-permission-scope";
 import { PermissionState } from "@capacitor/core";
-import { PluginPermission } from "../schemas/enums/plugin-permission";
 
+/**
+ * @since 7.1.0
+ */
 export interface CalendarAccess {
   /**
-   * Retrieves the current permission status for a given permission alias.
+   * Retrieves the current permission state for a given permission scope.
    *
    * @since 0.1.0
    * @platform Android, iOS
    *
    * @example
-   * CapacitorCalendar.checkPermission({ alias: 'readCalendar' });
+   * CapacitorCalendar.checkPermission({ scope: CalendarPermissionScope.READ_CALENDAR });
    */
   checkPermission(options: {
-    alias: PluginPermission;
+    scope: CalendarPermissionScope;
   }): Promise<{ result: PermissionState }>;
 
   /**
-   * Retrieves the current status of all permissions.
+   * Retrieves the current state of all permissions.
    *
    * @since 0.1.0
    * @platform Android, iOS
    */
   checkAllPermissions(): Promise<{ result: CheckAllPermissionsResult }>;
 
   /**
-   * Requests permission for a given permission alias.
+   * Requests permission for a given permission scope.
    *
    * @since 0.1.0
    * @platform Android, iOS
    *
    * @example
-   * this.requestPermission({ alias: 'readCalendar' });
+   * this.requestPermission({ scope: CalendarPermissionScope.READ_CALENDAR });
    */
   requestPermission(options: {
-    alias: PluginPermission;
+    scope: CalendarPermissionScope;
   }): Promise<{ result: PermissionState }>;
 
   /**
@@ -49,6 +52,12 @@ export interface CalendarAccess {
    *
    * @since 5.4.0
    * @platform Android, iOS
+   * @permissions
+   * | Platform  | Required |
+   * |-----------|---------------------|
+   * | iOS 17+   | `NSCalendarsWriteOnlyAccessUsageDescription` |
+   * | iOS 13-16 | `NSCalendarsUsageDescription` |
+   * | Android   | `android.permission.WRITE_CALENDAR` |
    */
   requestWriteOnlyCalendarAccess(): Promise<{ result: PermissionState }>;
 
@@ -57,6 +66,10 @@ export interface CalendarAccess {
    *
    * @since 5.4.0
    * @platform Android
+   * @permissions
+   * | Platform  | Required |
+   * |-----------|---------------------|
+   * | Android   | `android.permission.READ_CALENDAR` |
    */
   requestReadOnlyCalendarAccess(): Promise<{ result: PermissionState }>;
 
@@ -65,24 +78,22 @@ export interface CalendarAccess {
    *
    * @since 5.4.0
    * @platform Android, iOS
+   * @permissions
+   * | Platform  | Required |
+   * |-----------|---------------------|
+   * | iOS 17+   | `NSCalendarsFullAccessUsageDescription` |
+   * | iOS 13-16 | `NSCalendarsUsageDescription` |
+   * | Android   | `android.permission.READ_CALENDAR` & `android.permission.WRITE_CALENDAR` |
    */
   requestFullCalendarAccess(): Promise<{ result: PermissionState }>;
-
-  /**
-   * Requests read and write access to the reminders.
-   *
-   * @since 5.4.0
-   * @platform iOS
-   */
-  requestFullRemindersAccess(): Promise<{ result: PermissionState }>;
 }
 
 /**
  * @since 7.1.0
  * @platform Android, iOS
  */
 export type CheckAllPermissionsResult = Record<
-  PluginPermission,
+  CalendarPermissionScope,
   PermissionState
 >;
 

diff --git a/src/sub-definitions/reminders-access.ts b/src/sub-definitions/reminders-access.ts
@@ -0,0 +1,20 @@
+import { PermissionState } from "@capacitor/core";
+
+/**
+ * @since 7.1.0
+ */
+export interface RemindersAccess {
+  /**
+   * Requests read and write access to the reminders.
+   *
+   * @since 5.4.0
+   * @platform iOS
+   * @see {@link CalendarPermissionScope}
+   * @permissions
+   * | Platform  | Required |
+   * |-----------|---------------------|
+   * | iOS 17+   | `NSRemindersFullAccessUsageDescription` |
+   * | iOS 10-16 | `NSRemindersUsageDescription` |
+   */
+  requestFullRemindersAccess(): Promise<{ result: PermissionState }>;
+}