0
# Unimodules Permissions Interface
1

2
The `unimodules-permissions-interface` package provides a standardized interface for handling permissions across React Native and Expo applications. It defines TypeScript types and enums for permission status management, and provides native platform interfaces for iOS and Android implementations to ensure consistent permission handling across platforms.
3

4
## Package Information
5

6
- **Package Name**: unimodules-permissions-interface
7
- **Package Type**: npm
8
- **Language**: TypeScript with Native Platform Interfaces
9
- **Installation**: `npm install unimodules-permissions-interface`
10

11
## Core Imports
12

13
```typescript
14
import { PermissionStatus, PermissionResponse, PermissionExpiration } from "unimodules-permissions-interface";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { PermissionStatus, PermissionResponse, PermissionExpiration } = require("unimodules-permissions-interface");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { PermissionStatus, PermissionResponse } from "unimodules-permissions-interface";
27

28
// Example permission response
29
const permissionResponse: PermissionResponse = {
30
  status: PermissionStatus.GRANTED,
31
  expires: "never",
32
  granted: true,
33
  canAskAgain: false
34
};
35

36
// Check permission status
37
if (permissionResponse.status === PermissionStatus.GRANTED) {
38
  console.log("Permission granted");
39
} else if (permissionResponse.status === PermissionStatus.DENIED) {
40
  console.log("Permission denied");
41
} else {
42
  console.log("Permission undetermined");
43
}
44
```
45

46
## Capabilities
47

48
### Permission Status Management
49

50
Defines standardized permission states for cross-platform consistency.
51

52
```typescript { .api }
53
enum PermissionStatus {
54
  GRANTED = 'granted',
55
  UNDETERMINED = 'undetermined',
56
  DENIED = 'denied',
57
}
58
```
59

60
The `PermissionStatus` enum provides three possible states:
61
- `GRANTED`: Permission has been explicitly granted by the user
62
- `UNDETERMINED`: Permission has not been requested yet or status is unknown
63
- `DENIED`: Permission has been explicitly denied by the user
64

65
### Permission Response Structure
66

67
Standardized response object for permission requests across platforms.
68

69
```typescript { .api }
70
interface PermissionResponse {
71
  status: PermissionStatus;
72
  expires: PermissionExpiration;
73
  granted: boolean;
74
  canAskAgain: boolean;
75
}
76
```
77

78
**Properties:**
79
- `status`: Current permission status using `PermissionStatus` enum
80
- `expires`: When the permission expires (either 'never' or timestamp)
81
- `granted`: Boolean indicating if permission is currently granted
82
- `canAskAgain`: Boolean indicating if the user can be prompted again
83

84
### Permission Expiration
85

86
Defines when a permission expires.
87

88
```typescript { .api }
89
type PermissionExpiration = 'never' | number;
90
```
91

92
**Values:**
93
- `'never'`: Permission does not expire
94
- `number`: Unix timestamp when permission expires
95

96
## Native Platform Interfaces
97

98
This package provides native interfaces for platform-specific implementations. These are typically used by native modules and not directly by JavaScript/TypeScript code.
99

100
### Android Interface (Java)
101

102
The Android interface provides methods for permission management:
103

104
```java { .api }
105
public interface Permissions {
106
  // Get permission status asynchronously
107
  void getPermissionsWithPromise(final Promise promise, String... permissions);
108
  
109
  // Request permissions asynchronously
110
  void askForPermissionsWithPromise(final Promise promise, String... permissions);
111
  
112
  // Get permission status with callback
113
  void getPermissions(final PermissionsResponseListener response, String... permissions);
114
  
115
  // Request permissions with callback
116
  void askForPermissions(final PermissionsResponseListener response, String... permissions);
117
  
118
  // Check if permissions are granted (synchronous)
119
  boolean hasGrantedPermissions(String... permissions);
120
  
121
  // Check if permission is declared in AndroidManifest
122
  boolean isPermissionPresentInManifest(String permission);
123
}
124
```
125

126
**Static Helper Methods:**
127
```java { .api }
128
// Helper to get permissions with null checking
129
static void getPermissionsWithPermissionsManager(
130
  Permissions permissionsManager, 
131
  final Promise promise, 
132
  String... permissions
133
);
134

135
// Helper to request permissions with null checking
136
static void askForPermissionsWithPermissionsManager(
137
  Permissions permissionsManager, 
138
  final Promise promise, 
139
  String... permissions
140
);
141
```
142

143
### Android Permission Status Enum
144

145
```java { .api }
146
public enum PermissionsStatus {
147
  GRANTED("granted"),
148
  UNDETERMINED("undetermined"),
149
  DENIED("denied");
150
  
151
  public String getStatus();
152
}
153
```
154

155
### Android Response Callback
156

157
```java { .api }
158
@FunctionalInterface
159
public interface PermissionsResponseListener {
160
  void onResult(Map<String, PermissionsResponse> result);
161
}
162
```
163

164
### Android Response Data Class (Kotlin)
165

166
```kotlin { .api }
167
data class PermissionsResponse(
168
  val status: PermissionsStatus,
169
  val canAskAgain: Boolean = true
170
)
171
```
172

173
**Constants available:**
174
- `STATUS_KEY = "status"`
175
- `GRANTED_KEY = "granted"`
176
- `EXPIRES_KEY = "expires"`
177
- `CAN_ASK_AGAIN_KEY = "canAskAgain"`
178
- `SCOPE_KEY = "scope"`
179
- `PERMISSION_EXPIRES_NEVER = "never"`
180
- `SCOPE_IN_USE = "whenInUse"`
181
- `SCOPE_ALWAYS = "always"`
182
- `SCOPE_NONE = "none"`
183

184
### iOS Interface (Objective-C)
185

186
The iOS interface provides protocols for permission management:
187

188
```objc { .api }
189
// Permission status enum
190
typedef enum UMPermissionStatus {
191
  UMPermissionStatusDenied,
192
  UMPermissionStatusGranted,
193
  UMPermissionStatusUndetermined,
194
} UMPermissionStatus;
195

196
// Protocol for permission requesters
197
@protocol UMPermissionsRequester <NSObject>
198
+ (NSString *)permissionType;
199
- (void)requestPermissionsWithResolver:(UMPromiseResolveBlock)resolve 
200
                              rejecter:(UMPromiseRejectBlock)reject;
201
- (NSDictionary *)getPermissions;
202
@end
203

204
// Main permissions interface
205
@protocol UMPermissionsInterface
206
- (void)registerRequesters:(NSArray<id<UMPermissionsRequester>> *)newRequesters;
207

208
- (void)getPermissionUsingRequesterClass:(Class)requesterClass
209
                                 resolve:(UMPromiseResolveBlock)resolve
210
                                  reject:(UMPromiseRejectBlock)reject;
211

212
- (BOOL)hasGrantedPermissionUsingRequesterClass:(Class)requesterClass;
213

214
- (void)askForPermissionUsingRequesterClass:(Class)requesterClass
215
                                    resolve:(UMPromiseResolveBlock)resolve
216
                                     reject:(UMPromiseRejectBlock)reject;
217

218
- (id<UMPermissionsRequester>)getPermissionRequesterForType:(NSString *)type;
219
@end
220
```
221

222
### iOS Helper Delegate
223

224
```objc { .api }
225
@interface UMPermissionsMethodsDelegate : NSObject
226

227
+ (void)getPermissionWithPermissionsManager:(id<UMPermissionsInterface>)permissionsManager
228
                              withRequester:(Class)requesterClass
229
                                    resolve:(UMPromiseResolveBlock)resolve
230
                                     reject:(UMPromiseRejectBlock)reject;
231

232
+ (void)askForPermissionWithPermissionsManager:(id<UMPermissionsInterface>)permissionsManager
233
                                 withRequester:(Class)requesterClass
234
                                       resolve:(UMPromiseResolveBlock)resolve
235
                                        reject:(UMPromiseRejectBlock)reject;
236

237
+ (void)registerRequesters:(NSArray<id<UMPermissionsRequester>> *)newRequesters
238
    withPermissionsManager:(id<UMPermissionsInterface>)permissionsManager;
239

240
@end
241
```
242

243
### iOS User Notification Center Proxy
244

245
```objc { .api }  
246
@protocol UMUserNotificationCenterProxyInterface <NSObject>
247

248
- (void)getNotificationSettingsWithCompletionHandler:(nonnull void(^)(UNNotificationSettings *__nonnull settings))completionHandler;
249

250
- (void)requestAuthorizationWithOptions:(UNAuthorizationOptions)options 
251
                      completionHandler:(nonnull void (^)(BOOL granted, NSError *__nullable error))completionHandler;
252

253
@end
254
```
255

256
## Implementation Notes
257

258
This package serves as an interface specification - it defines the contracts that concrete permission implementations must follow. Native modules implementing specific permissions (camera, location, notifications, etc.) should extend these interfaces to provide actual permission handling functionality.
259

260
The TypeScript types ensure consistent JavaScript API across all permission modules, while the native interfaces ensure consistent platform-specific implementations. This architecture allows Expo and React Native applications to handle permissions uniformly regardless of the specific permission type or platform.