react-native-cloud-sync 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (268) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +360 -0
  3. package/app.plugin.js +3 -0
  4. package/ios/CloudSyncError.swift +144 -0
  5. package/ios/CloudSyncImpl.swift +1263 -0
  6. package/ios/RNCloudSync.h +25 -0
  7. package/ios/RNCloudSync.mm +477 -0
  8. package/jest-mock.js +136 -0
  9. package/lib/commonjs/config.js +85 -0
  10. package/lib/commonjs/config.js.map +1 -0
  11. package/lib/commonjs/errors.js +244 -0
  12. package/lib/commonjs/errors.js.map +1 -0
  13. package/lib/commonjs/hooks.js +257 -0
  14. package/lib/commonjs/hooks.js.map +1 -0
  15. package/lib/commonjs/index.js +244 -0
  16. package/lib/commonjs/index.js.map +1 -0
  17. package/lib/commonjs/internal/autoFlush.js +65 -0
  18. package/lib/commonjs/internal/autoFlush.js.map +1 -0
  19. package/lib/commonjs/internal/base64.js +58 -0
  20. package/lib/commonjs/internal/base64.js.map +1 -0
  21. package/lib/commonjs/internal/bytes.js +32 -0
  22. package/lib/commonjs/internal/bytes.js.map +1 -0
  23. package/lib/commonjs/internal/cloudKitRest.js +527 -0
  24. package/lib/commonjs/internal/cloudKitRest.js.map +1 -0
  25. package/lib/commonjs/internal/enums.js +23 -0
  26. package/lib/commonjs/internal/enums.js.map +1 -0
  27. package/lib/commonjs/internal/googleDriveRest.js +624 -0
  28. package/lib/commonjs/internal/googleDriveRest.js.map +1 -0
  29. package/lib/commonjs/internal/keys.js +139 -0
  30. package/lib/commonjs/internal/keys.js.map +1 -0
  31. package/lib/commonjs/internal/logger.js +29 -0
  32. package/lib/commonjs/internal/logger.js.map +1 -0
  33. package/lib/commonjs/internal/nativeModule.js +125 -0
  34. package/lib/commonjs/internal/nativeModule.js.map +1 -0
  35. package/lib/commonjs/internal/timeout.js +72 -0
  36. package/lib/commonjs/internal/timeout.js.map +1 -0
  37. package/lib/commonjs/package.json +1 -0
  38. package/lib/commonjs/providers/cloudKit.js +398 -0
  39. package/lib/commonjs/providers/cloudKit.js.map +1 -0
  40. package/lib/commonjs/providers/cloudKitBackup.js +86 -0
  41. package/lib/commonjs/providers/cloudKitBackup.js.map +1 -0
  42. package/lib/commonjs/providers/cloudKitEncrypted.js +150 -0
  43. package/lib/commonjs/providers/cloudKitEncrypted.js.map +1 -0
  44. package/lib/commonjs/providers/googleDrive.js +219 -0
  45. package/lib/commonjs/providers/googleDrive.js.map +1 -0
  46. package/lib/commonjs/providers/googleDriveFiles.js +68 -0
  47. package/lib/commonjs/providers/googleDriveFiles.js.map +1 -0
  48. package/lib/commonjs/providers/icloudDocuments.js +121 -0
  49. package/lib/commonjs/providers/icloudDocuments.js.map +1 -0
  50. package/lib/commonjs/providers/icloudKV.js +171 -0
  51. package/lib/commonjs/providers/icloudKV.js.map +1 -0
  52. package/lib/commonjs/providers/icloudKV.web.js +42 -0
  53. package/lib/commonjs/providers/icloudKV.web.js.map +1 -0
  54. package/lib/commonjs/providers/memory.js +201 -0
  55. package/lib/commonjs/providers/memory.js.map +1 -0
  56. package/lib/commonjs/resolvers.js +128 -0
  57. package/lib/commonjs/resolvers.js.map +1 -0
  58. package/lib/commonjs/specs/NativeRNCloudSync.js +14 -0
  59. package/lib/commonjs/specs/NativeRNCloudSync.js.map +1 -0
  60. package/lib/commonjs/store.js +1064 -0
  61. package/lib/commonjs/store.js.map +1 -0
  62. package/lib/commonjs/testing.js +32 -0
  63. package/lib/commonjs/testing.js.map +1 -0
  64. package/lib/commonjs/types.js +86 -0
  65. package/lib/commonjs/types.js.map +1 -0
  66. package/lib/module/config.js +72 -0
  67. package/lib/module/config.js.map +1 -0
  68. package/lib/module/errors.js +231 -0
  69. package/lib/module/errors.js.map +1 -0
  70. package/lib/module/hooks.js +250 -0
  71. package/lib/module/hooks.js.map +1 -0
  72. package/lib/module/index.js +46 -0
  73. package/lib/module/index.js.map +1 -0
  74. package/lib/module/internal/autoFlush.js +62 -0
  75. package/lib/module/internal/autoFlush.js.map +1 -0
  76. package/lib/module/internal/base64.js +53 -0
  77. package/lib/module/internal/base64.js.map +1 -0
  78. package/lib/module/internal/bytes.js +28 -0
  79. package/lib/module/internal/bytes.js.map +1 -0
  80. package/lib/module/internal/cloudKitRest.js +518 -0
  81. package/lib/module/internal/cloudKitRest.js.map +1 -0
  82. package/lib/module/internal/enums.js +18 -0
  83. package/lib/module/internal/enums.js.map +1 -0
  84. package/lib/module/internal/googleDriveRest.js +620 -0
  85. package/lib/module/internal/googleDriveRest.js.map +1 -0
  86. package/lib/module/internal/keys.js +134 -0
  87. package/lib/module/internal/keys.js.map +1 -0
  88. package/lib/module/internal/logger.js +23 -0
  89. package/lib/module/internal/logger.js.map +1 -0
  90. package/lib/module/internal/nativeModule.js +117 -0
  91. package/lib/module/internal/nativeModule.js.map +1 -0
  92. package/lib/module/internal/timeout.js +67 -0
  93. package/lib/module/internal/timeout.js.map +1 -0
  94. package/lib/module/package.json +1 -0
  95. package/lib/module/providers/cloudKit.js +392 -0
  96. package/lib/module/providers/cloudKit.js.map +1 -0
  97. package/lib/module/providers/cloudKitBackup.js +82 -0
  98. package/lib/module/providers/cloudKitBackup.js.map +1 -0
  99. package/lib/module/providers/cloudKitEncrypted.js +146 -0
  100. package/lib/module/providers/cloudKitEncrypted.js.map +1 -0
  101. package/lib/module/providers/googleDrive.js +214 -0
  102. package/lib/module/providers/googleDrive.js.map +1 -0
  103. package/lib/module/providers/googleDriveFiles.js +64 -0
  104. package/lib/module/providers/googleDriveFiles.js.map +1 -0
  105. package/lib/module/providers/icloudDocuments.js +117 -0
  106. package/lib/module/providers/icloudDocuments.js.map +1 -0
  107. package/lib/module/providers/icloudKV.js +165 -0
  108. package/lib/module/providers/icloudKV.js.map +1 -0
  109. package/lib/module/providers/icloudKV.web.js +36 -0
  110. package/lib/module/providers/icloudKV.web.js.map +1 -0
  111. package/lib/module/providers/memory.js +197 -0
  112. package/lib/module/providers/memory.js.map +1 -0
  113. package/lib/module/resolvers.js +120 -0
  114. package/lib/module/resolvers.js.map +1 -0
  115. package/lib/module/specs/NativeRNCloudSync.js +12 -0
  116. package/lib/module/specs/NativeRNCloudSync.js.map +1 -0
  117. package/lib/module/store.js +1061 -0
  118. package/lib/module/store.js.map +1 -0
  119. package/lib/module/testing.js +17 -0
  120. package/lib/module/testing.js.map +1 -0
  121. package/lib/module/types.js +82 -0
  122. package/lib/module/types.js.map +1 -0
  123. package/lib/typescript/commonjs/config.d.ts +33 -0
  124. package/lib/typescript/commonjs/config.d.ts.map +1 -0
  125. package/lib/typescript/commonjs/errors.d.ts +140 -0
  126. package/lib/typescript/commonjs/errors.d.ts.map +1 -0
  127. package/lib/typescript/commonjs/hooks.d.ts +109 -0
  128. package/lib/typescript/commonjs/hooks.d.ts.map +1 -0
  129. package/lib/typescript/commonjs/index.d.ts +37 -0
  130. package/lib/typescript/commonjs/index.d.ts.map +1 -0
  131. package/lib/typescript/commonjs/internal/autoFlush.d.ts +45 -0
  132. package/lib/typescript/commonjs/internal/autoFlush.d.ts.map +1 -0
  133. package/lib/typescript/commonjs/internal/base64.d.ts +12 -0
  134. package/lib/typescript/commonjs/internal/base64.d.ts.map +1 -0
  135. package/lib/typescript/commonjs/internal/bytes.d.ts +12 -0
  136. package/lib/typescript/commonjs/internal/bytes.d.ts.map +1 -0
  137. package/lib/typescript/commonjs/internal/cloudKitRest.d.ts +149 -0
  138. package/lib/typescript/commonjs/internal/cloudKitRest.d.ts.map +1 -0
  139. package/lib/typescript/commonjs/internal/enums.d.ts +10 -0
  140. package/lib/typescript/commonjs/internal/enums.d.ts.map +1 -0
  141. package/lib/typescript/commonjs/internal/googleDriveRest.d.ts +232 -0
  142. package/lib/typescript/commonjs/internal/googleDriveRest.d.ts.map +1 -0
  143. package/lib/typescript/commonjs/internal/keys.d.ts +28 -0
  144. package/lib/typescript/commonjs/internal/keys.d.ts.map +1 -0
  145. package/lib/typescript/commonjs/internal/logger.d.ts +10 -0
  146. package/lib/typescript/commonjs/internal/logger.d.ts.map +1 -0
  147. package/lib/typescript/commonjs/internal/nativeModule.d.ts +29 -0
  148. package/lib/typescript/commonjs/internal/nativeModule.d.ts.map +1 -0
  149. package/lib/typescript/commonjs/internal/timeout.d.ts +36 -0
  150. package/lib/typescript/commonjs/internal/timeout.d.ts.map +1 -0
  151. package/lib/typescript/commonjs/package.json +1 -0
  152. package/lib/typescript/commonjs/providers/cloudKit.d.ts +86 -0
  153. package/lib/typescript/commonjs/providers/cloudKit.d.ts.map +1 -0
  154. package/lib/typescript/commonjs/providers/cloudKitBackup.d.ts +65 -0
  155. package/lib/typescript/commonjs/providers/cloudKitBackup.d.ts.map +1 -0
  156. package/lib/typescript/commonjs/providers/cloudKitEncrypted.d.ts +37 -0
  157. package/lib/typescript/commonjs/providers/cloudKitEncrypted.d.ts.map +1 -0
  158. package/lib/typescript/commonjs/providers/googleDrive.d.ts +35 -0
  159. package/lib/typescript/commonjs/providers/googleDrive.d.ts.map +1 -0
  160. package/lib/typescript/commonjs/providers/googleDriveFiles.d.ts +59 -0
  161. package/lib/typescript/commonjs/providers/googleDriveFiles.d.ts.map +1 -0
  162. package/lib/typescript/commonjs/providers/icloudDocuments.d.ts +101 -0
  163. package/lib/typescript/commonjs/providers/icloudDocuments.d.ts.map +1 -0
  164. package/lib/typescript/commonjs/providers/icloudKV.d.ts +26 -0
  165. package/lib/typescript/commonjs/providers/icloudKV.d.ts.map +1 -0
  166. package/lib/typescript/commonjs/providers/icloudKV.web.d.ts +12 -0
  167. package/lib/typescript/commonjs/providers/icloudKV.web.d.ts.map +1 -0
  168. package/lib/typescript/commonjs/providers/memory.d.ts +90 -0
  169. package/lib/typescript/commonjs/providers/memory.d.ts.map +1 -0
  170. package/lib/typescript/commonjs/resolvers.d.ts +60 -0
  171. package/lib/typescript/commonjs/resolvers.d.ts.map +1 -0
  172. package/lib/typescript/commonjs/specs/NativeRNCloudSync.d.ts +133 -0
  173. package/lib/typescript/commonjs/specs/NativeRNCloudSync.d.ts.map +1 -0
  174. package/lib/typescript/commonjs/store.d.ts +118 -0
  175. package/lib/typescript/commonjs/store.d.ts.map +1 -0
  176. package/lib/typescript/commonjs/testing.d.ts +16 -0
  177. package/lib/typescript/commonjs/testing.d.ts.map +1 -0
  178. package/lib/typescript/commonjs/types.d.ts +367 -0
  179. package/lib/typescript/commonjs/types.d.ts.map +1 -0
  180. package/lib/typescript/module/config.d.ts +33 -0
  181. package/lib/typescript/module/config.d.ts.map +1 -0
  182. package/lib/typescript/module/errors.d.ts +140 -0
  183. package/lib/typescript/module/errors.d.ts.map +1 -0
  184. package/lib/typescript/module/hooks.d.ts +109 -0
  185. package/lib/typescript/module/hooks.d.ts.map +1 -0
  186. package/lib/typescript/module/index.d.ts +37 -0
  187. package/lib/typescript/module/index.d.ts.map +1 -0
  188. package/lib/typescript/module/internal/autoFlush.d.ts +45 -0
  189. package/lib/typescript/module/internal/autoFlush.d.ts.map +1 -0
  190. package/lib/typescript/module/internal/base64.d.ts +12 -0
  191. package/lib/typescript/module/internal/base64.d.ts.map +1 -0
  192. package/lib/typescript/module/internal/bytes.d.ts +12 -0
  193. package/lib/typescript/module/internal/bytes.d.ts.map +1 -0
  194. package/lib/typescript/module/internal/cloudKitRest.d.ts +149 -0
  195. package/lib/typescript/module/internal/cloudKitRest.d.ts.map +1 -0
  196. package/lib/typescript/module/internal/enums.d.ts +10 -0
  197. package/lib/typescript/module/internal/enums.d.ts.map +1 -0
  198. package/lib/typescript/module/internal/googleDriveRest.d.ts +232 -0
  199. package/lib/typescript/module/internal/googleDriveRest.d.ts.map +1 -0
  200. package/lib/typescript/module/internal/keys.d.ts +28 -0
  201. package/lib/typescript/module/internal/keys.d.ts.map +1 -0
  202. package/lib/typescript/module/internal/logger.d.ts +10 -0
  203. package/lib/typescript/module/internal/logger.d.ts.map +1 -0
  204. package/lib/typescript/module/internal/nativeModule.d.ts +29 -0
  205. package/lib/typescript/module/internal/nativeModule.d.ts.map +1 -0
  206. package/lib/typescript/module/internal/timeout.d.ts +36 -0
  207. package/lib/typescript/module/internal/timeout.d.ts.map +1 -0
  208. package/lib/typescript/module/package.json +1 -0
  209. package/lib/typescript/module/providers/cloudKit.d.ts +86 -0
  210. package/lib/typescript/module/providers/cloudKit.d.ts.map +1 -0
  211. package/lib/typescript/module/providers/cloudKitBackup.d.ts +65 -0
  212. package/lib/typescript/module/providers/cloudKitBackup.d.ts.map +1 -0
  213. package/lib/typescript/module/providers/cloudKitEncrypted.d.ts +37 -0
  214. package/lib/typescript/module/providers/cloudKitEncrypted.d.ts.map +1 -0
  215. package/lib/typescript/module/providers/googleDrive.d.ts +35 -0
  216. package/lib/typescript/module/providers/googleDrive.d.ts.map +1 -0
  217. package/lib/typescript/module/providers/googleDriveFiles.d.ts +59 -0
  218. package/lib/typescript/module/providers/googleDriveFiles.d.ts.map +1 -0
  219. package/lib/typescript/module/providers/icloudDocuments.d.ts +101 -0
  220. package/lib/typescript/module/providers/icloudDocuments.d.ts.map +1 -0
  221. package/lib/typescript/module/providers/icloudKV.d.ts +26 -0
  222. package/lib/typescript/module/providers/icloudKV.d.ts.map +1 -0
  223. package/lib/typescript/module/providers/icloudKV.web.d.ts +12 -0
  224. package/lib/typescript/module/providers/icloudKV.web.d.ts.map +1 -0
  225. package/lib/typescript/module/providers/memory.d.ts +90 -0
  226. package/lib/typescript/module/providers/memory.d.ts.map +1 -0
  227. package/lib/typescript/module/resolvers.d.ts +60 -0
  228. package/lib/typescript/module/resolvers.d.ts.map +1 -0
  229. package/lib/typescript/module/specs/NativeRNCloudSync.d.ts +133 -0
  230. package/lib/typescript/module/specs/NativeRNCloudSync.d.ts.map +1 -0
  231. package/lib/typescript/module/store.d.ts +118 -0
  232. package/lib/typescript/module/store.d.ts.map +1 -0
  233. package/lib/typescript/module/testing.d.ts +16 -0
  234. package/lib/typescript/module/testing.d.ts.map +1 -0
  235. package/lib/typescript/module/types.d.ts +367 -0
  236. package/lib/typescript/module/types.d.ts.map +1 -0
  237. package/package.json +186 -0
  238. package/plugin/build/index.d.ts +45 -0
  239. package/plugin/build/index.js +93 -0
  240. package/react-native-cloud-sync.podspec +48 -0
  241. package/src/config.ts +94 -0
  242. package/src/errors.ts +263 -0
  243. package/src/hooks.ts +337 -0
  244. package/src/index.ts +113 -0
  245. package/src/internal/autoFlush.ts +87 -0
  246. package/src/internal/base64.ts +63 -0
  247. package/src/internal/bytes.ts +28 -0
  248. package/src/internal/cloudKitRest.ts +654 -0
  249. package/src/internal/enums.ts +35 -0
  250. package/src/internal/googleDriveRest.ts +765 -0
  251. package/src/internal/keys.ts +160 -0
  252. package/src/internal/logger.ts +23 -0
  253. package/src/internal/nativeModule.ts +149 -0
  254. package/src/internal/timeout.ts +83 -0
  255. package/src/providers/cloudKit.ts +510 -0
  256. package/src/providers/cloudKitBackup.ts +124 -0
  257. package/src/providers/cloudKitEncrypted.ts +175 -0
  258. package/src/providers/googleDrive.ts +251 -0
  259. package/src/providers/googleDriveFiles.ts +117 -0
  260. package/src/providers/icloudDocuments.ts +175 -0
  261. package/src/providers/icloudKV.ts +206 -0
  262. package/src/providers/icloudKV.web.ts +41 -0
  263. package/src/providers/memory.ts +302 -0
  264. package/src/resolvers.ts +133 -0
  265. package/src/specs/NativeRNCloudSync.ts +184 -0
  266. package/src/store.ts +1288 -0
  267. package/src/testing.ts +22 -0
  268. package/src/types.ts +426 -0
@@ -0,0 +1,175 @@
1
+ import { Platform } from 'react-native'
2
+
3
+ import { getNativeModule, requireNativeModule } from '../internal/nativeModule'
4
+ import { normalizeError, unsupportedPlatform } from '../errors'
5
+
6
+ const NAME = 'icloudDocuments' as const
7
+
8
+ const APPLE_PLATFORMS = ['ios', 'macos'] as const
9
+
10
+ /** Default wait for a file to come down from iCloud before reporting a timeout. */
11
+ const DEFAULT_FETCH_TIMEOUT_MS = 60_000
12
+
13
+ function isApplePlatform(): boolean {
14
+ const os: string | undefined = Platform?.OS
15
+ return os != null && (APPLE_PLATFORMS as readonly string[]).includes(os)
16
+ }
17
+
18
+ function assertSupported(): void {
19
+ if (!isApplePlatform() || getNativeModule() == null)
20
+ throw unsupportedPlatform(
21
+ NAME,
22
+ 'iCloud Drive is an Apple filesystem feature with no REST or browser equivalent. '
23
+ + 'Use googleDriveFiles for user-visible files on Android and web.'
24
+ )
25
+ }
26
+
27
+ export interface DocumentEntry {
28
+ name: string
29
+ sizeBytes: number
30
+ /**
31
+ * False when the file exists in the account but has no local copy on this
32
+ * device.
33
+ *
34
+ * The distinction that makes iCloud Drive different from a normal directory:
35
+ * a listing shows files this device has never downloaded, and reading one
36
+ * without calling {@link icloudDocuments.fetch} first gives you nothing.
37
+ */
38
+ isDownloaded: boolean
39
+ isDownloading: boolean
40
+ }
41
+
42
+ export interface DocumentFetchOptions {
43
+ /**
44
+ * Copy the file here once it is downloaded, and resolve this path instead of
45
+ * the in-container one.
46
+ *
47
+ * Worth doing for anything you intend to keep: the system may evict a
48
+ * downloaded copy from the container to reclaim space, turning it back into a
49
+ * placeholder.
50
+ */
51
+ destinationUri?: string
52
+ /**
53
+ * How long to wait for the download. Default 60000.
54
+ *
55
+ * A timeout is not a failure of the transfer - iOS keeps downloading in the
56
+ * background - so `ERR_TIMEOUT` here means "not yet", and it is classified as
57
+ * retryable for exactly that reason.
58
+ */
59
+ timeoutMs?: number
60
+ }
61
+
62
+ /**
63
+ * Files in the user's own iCloud Drive.
64
+ *
65
+ * This is the one thing no `CKRecord` or `CKAsset` API can do, and the most
66
+ * common iCloud request in mobile apps: *put this file where the user can find
67
+ * it*. A `CKAsset` lives in the app's private CloudKit database - the user
68
+ * cannot see it, open it, or hand it to another app. A file written here lands
69
+ * in the app's folder in iCloud Drive, visible in Files.app, syncing to every
70
+ * device signed into the same Apple ID, and surviving the app being deleted.
71
+ *
72
+ * Requirements beyond the CloudKit entitlement:
73
+ *
74
+ * - the **iCloud Documents** service on the container (the config plugin's
75
+ * `iCloudDocuments: true` option adds it);
76
+ * - an `NSUbiquitousContainers` Info.plist entry with
77
+ * `NSUbiquitousContainerIsDocumentScopePublic` set, or the folder syncs but
78
+ * stays invisible in Files.app. The plugin writes this too.
79
+ *
80
+ * Apple platforms only, and unlike the other providers that is not a gap to be
81
+ * filled later: there is no REST surface for iCloud Drive and no browser API.
82
+ * Use {@link googleDriveFiles} for user-visible files elsewhere.
83
+ *
84
+ * Not a {@link CloudProvider}: the contract there is keys to string values, and
85
+ * this moves files by path. Same reason `cloudKitAssets` is its own API.
86
+ */
87
+ export const icloudDocuments = {
88
+ /** Whether this device has a usable iCloud Drive container right now. */
89
+ isAvailable: async (): Promise<boolean> => {
90
+ if (!isApplePlatform()) return false
91
+ const m = getNativeModule()
92
+ if (m == null) return false
93
+ try {
94
+ return await m.docIsAvailable()
95
+ }
96
+ catch {
97
+ return false
98
+ }
99
+ },
100
+
101
+ /**
102
+ * Copies a local file into iCloud Drive under `name`, replacing whatever was
103
+ * there. Resolves the resulting iCloud path.
104
+ *
105
+ * Resolving means "handed to iCloud", not "in the cloud" - the system uploads
106
+ * in the background whether or not the app is running. Same distinction as
107
+ * `icloudKVSync()`, and for the same reason: there is no API that waits for
108
+ * the upload.
109
+ */
110
+ save: async (options: { fileUri: string; name: string }): Promise<string> => {
111
+ assertSupported()
112
+ try {
113
+ return await requireNativeModule().docSave(options.fileUri, options.name)
114
+ }
115
+ catch (e) {
116
+ throw normalizeError(e, NAME)
117
+ }
118
+ },
119
+
120
+ /**
121
+ * Downloads `name` if this device does not have it yet, then resolves a local
122
+ * path - or `null` when no such file exists in the account.
123
+ *
124
+ * The download step is the point. A file listed by {@link list} may be a
125
+ * placeholder with no local bytes, and opening that gives you an empty file
126
+ * rather than an error.
127
+ *
128
+ * Byte-level progress is not reported: that needs an `NSMetadataQuery`, which
129
+ * needs a live run loop, and this runs off the main thread on purpose. Use
130
+ * {@link list} to poll `isDownloading` if you need to show something.
131
+ */
132
+ fetch: async (
133
+ options: { name: string } & DocumentFetchOptions
134
+ ): Promise<string | null> => {
135
+ assertSupported()
136
+ try {
137
+ return await requireNativeModule().docFetch(
138
+ options.name,
139
+ options.destinationUri ?? null,
140
+ options.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS
141
+ )
142
+ }
143
+ catch (e) {
144
+ throw normalizeError(e, NAME)
145
+ }
146
+ },
147
+
148
+ /**
149
+ * Everything in the app's iCloud Drive folder, including files this device
150
+ * has not downloaded.
151
+ */
152
+ list: async (): Promise<DocumentEntry[]> => {
153
+ assertSupported()
154
+ try {
155
+ return await requireNativeModule().docList()
156
+ }
157
+ catch (e) {
158
+ throw normalizeError(e, NAME)
159
+ }
160
+ },
161
+
162
+ /**
163
+ * Deletes a file from iCloud Drive - on every device, and from the user's
164
+ * Files.app. Resolves false when it was already gone.
165
+ */
166
+ remove: async (name: string): Promise<boolean> => {
167
+ assertSupported()
168
+ try {
169
+ return await requireNativeModule().docRemove(name)
170
+ }
171
+ catch (e) {
172
+ throw normalizeError(e, NAME)
173
+ }
174
+ },
175
+ }
@@ -0,0 +1,206 @@
1
+ import { Platform } from 'react-native'
2
+
3
+ import {
4
+ getNativeModule,
5
+ requireNativeModule,
6
+ subscribeNativeEvent,
7
+ } from '../internal/nativeModule'
8
+ import { normalizeError, unsupportedPlatform } from '../errors'
9
+ import type {
10
+ AccountChangeEvent,
11
+ AccountStatus,
12
+ CloudProvider,
13
+ RemoteChangeEvent,
14
+ Unsubscribe,
15
+ } from '../types'
16
+ import type {
17
+ AccountChangeNativeEvent,
18
+ RemoteChangeNativeEvent,
19
+ } from '../specs/NativeRNCloudSync'
20
+ import { toAccountStatus, toChangeReason } from '../internal/enums'
21
+
22
+ const NAME = 'icloudKV' as const
23
+
24
+ /**
25
+ * `NSUbiquitousKeyValueStore`.
26
+ *
27
+ * Apple-only by construction: there is no browser or Android API for the iCloud
28
+ * key-value store, and no REST surface either. Reach for `cloudKit` when you
29
+ * need the same data on Android or web.
30
+ *
31
+ * Hard limits, enforced here rather than left to fail silently at the OS layer:
32
+ * 1 MB total, 1 MB per key, 1024 keys.
33
+ */
34
+ const APPLE_PLATFORMS = ['ios', 'macos'] as const
35
+
36
+ /**
37
+ * True on a platform where `NSUbiquitousKeyValueStore` can exist at all.
38
+ *
39
+ * `Platform.OS` is read defensively because a non-Metro web bundler
40
+ * (webpack/Vite/Next) does not resolve the `.web.ts` platform extension, so
41
+ * this file - not `icloudKV.web.ts` - is what a react-native-web build loads.
42
+ * It must reach the same conclusion there by itself.
43
+ */
44
+ function isApplePlatform(): boolean {
45
+ const os: string | undefined = Platform?.OS
46
+ return os != null && (APPLE_PLATFORMS as readonly string[]).includes(os)
47
+ }
48
+
49
+ function assertPlatform(): void {
50
+ if (!isApplePlatform())
51
+ throw unsupportedPlatform(
52
+ NAME,
53
+ `NSUbiquitousKeyValueStore exists only on Apple platforms (got '${String(Platform?.OS)}'). `
54
+ + `Use the cloudKit provider for cross-platform access to the same account.`
55
+ )
56
+ }
57
+
58
+ export const icloudKV: CloudProvider = {
59
+ name: NAME,
60
+
61
+ isAvailable: async () => {
62
+ if (!isApplePlatform()) return false
63
+ const m = getNativeModule()
64
+ if (m == null) return false
65
+ try {
66
+ return await m.isAvailable()
67
+ }
68
+ catch {
69
+ return false
70
+ }
71
+ },
72
+
73
+ getAccountStatus: async (): Promise<AccountStatus> => {
74
+ assertPlatform()
75
+ try {
76
+ return toAccountStatus(await requireNativeModule().getAccountStatus())
77
+ }
78
+ catch (e) {
79
+ throw normalizeError(e, NAME)
80
+ }
81
+ },
82
+
83
+ getItem: async (key: string) => {
84
+ assertPlatform()
85
+ try {
86
+ return await requireNativeModule().kvGetItem(key)
87
+ }
88
+ catch (e) {
89
+ throw normalizeError(e, NAME)
90
+ }
91
+ },
92
+
93
+ setItem: async (key: string, value: string) => {
94
+ assertPlatform()
95
+ try {
96
+ await requireNativeModule().kvSetItem(key, value)
97
+ }
98
+ catch (e) {
99
+ throw normalizeError(e, NAME)
100
+ }
101
+ },
102
+
103
+ removeItem: async (key: string) => {
104
+ assertPlatform()
105
+ try {
106
+ await requireNativeModule().kvRemoveItem(key)
107
+ }
108
+ catch (e) {
109
+ throw normalizeError(e, NAME)
110
+ }
111
+ },
112
+
113
+ getAllKeys: async () => {
114
+ assertPlatform()
115
+ try {
116
+ return await requireNativeModule().kvGetAllKeys()
117
+ }
118
+ catch (e) {
119
+ throw normalizeError(e, NAME)
120
+ }
121
+ },
122
+
123
+ /**
124
+ * How full the key-value store is.
125
+ *
126
+ * `totalBytes` is Apple's 1 MB ceiling rather than a per-account quota - the
127
+ * key-value store has a fixed size, not a share of the user's iCloud storage.
128
+ * The number worth watching, since exceeding it is silent.
129
+ */
130
+ getQuota: async () => {
131
+ if (!isApplePlatform()) return null
132
+ const m = getNativeModule()
133
+ if (m == null) return null
134
+ try {
135
+ const usage = await m.kvGetUsage()
136
+ return { usedBytes: usage.usedBytes, totalBytes: usage.totalBytes, provider: NAME }
137
+ }
138
+ catch (e) {
139
+ throw normalizeError(e, NAME)
140
+ }
141
+ },
142
+
143
+ onRemoteChange: (listener: (e: RemoteChangeEvent) => void): Unsubscribe =>
144
+ subscribeNativeEvent<RemoteChangeNativeEvent>(
145
+ 'onRemoteChange',
146
+ 'remoteChange',
147
+ (e) => {
148
+ if (e.provider !== NAME) return
149
+ listener({ keys: e.keys, reason: toChangeReason(e.reason), provider: NAME })
150
+ }
151
+ ),
152
+
153
+ onAccountChange: (listener: (e: AccountChangeEvent) => void): Unsubscribe =>
154
+ subscribeNativeEvent<AccountChangeNativeEvent>(
155
+ 'onAccountChange',
156
+ 'accountChange',
157
+ (e) => {
158
+ listener({
159
+ status: toAccountStatus(e.status),
160
+ identityChanged: e.identityChanged,
161
+ provider: NAME,
162
+ })
163
+ }
164
+ ),
165
+ }
166
+
167
+ /**
168
+ * Every key and value in the store, in one call.
169
+ *
170
+ * Not part of the {@link CloudProvider} contract, because no other provider can
171
+ * do it cheaply - CloudKit and Drive would both have to fetch every record.
172
+ * Here the whole store is already a local dictionary, so this is one bridge hop
173
+ * against the N+1 that `getAllKeys()` plus a read per key would cost.
174
+ *
175
+ * Values the store holds as something other than a string (it also accepts
176
+ * numbers, dates and data) are omitted rather than coerced, since a
177
+ * stringified number would not round-trip back through `setItem`.
178
+ */
179
+ export async function getAllItems(): Promise<Record<string, string>> {
180
+ assertPlatform()
181
+ try {
182
+ return await requireNativeModule().kvGetAllItems()
183
+ }
184
+ catch (e) {
185
+ throw normalizeError(e, NAME)
186
+ }
187
+ }
188
+
189
+ /**
190
+ * Flushes pending changes to disk.
191
+ *
192
+ * Exposed separately because it is not part of the generic {@link CloudProvider}
193
+ * contract - and because its semantics are routinely misread. It maps to
194
+ * `NSUbiquitousKeyValueStore.synchronize()`, which schedules an upload; it does
195
+ * not wait for or confirm one. A resolved `sync()` means "queued", never
196
+ * "stored in iCloud".
197
+ */
198
+ export async function sync(): Promise<boolean> {
199
+ assertPlatform()
200
+ try {
201
+ return await requireNativeModule().kvSync()
202
+ }
203
+ catch (e) {
204
+ throw normalizeError(e, NAME)
205
+ }
206
+ }
@@ -0,0 +1,41 @@
1
+ import { unsupportedPlatform } from '../errors'
2
+ import type { AccountStatus, CloudProvider } from '../types'
3
+
4
+ const NAME = 'icloudKV' as const
5
+
6
+ const DETAIL
7
+ = 'NSUbiquitousKeyValueStore has no browser API. Use the cloudKit provider, which '
8
+ + 'reaches the same private database over CloudKit Web Services.'
9
+
10
+ function reject(): never {
11
+ throw unsupportedPlatform(NAME, DETAIL)
12
+ }
13
+
14
+ /**
15
+ * Web build of the iCloud key-value provider.
16
+ *
17
+ * Every operation rejects with `ERR_UNSUPPORTED_PLATFORM` rather than resolving
18
+ * `null` or silently no-oping, so a web build fails loudly at the call site
19
+ * instead of appearing to work and quietly dropping data.
20
+ */
21
+ export const icloudKV: CloudProvider = {
22
+ name: NAME,
23
+ isAvailable: () => Promise.resolve(false),
24
+ getAccountStatus: (): Promise<AccountStatus> => Promise.resolve('couldNotDetermine'),
25
+ getItem: reject,
26
+ setItem: reject,
27
+ removeItem: reject,
28
+ getAllKeys: reject,
29
+ // Not `reject`: a quota question has a truthful answer on web - there is no
30
+ // key-value store here to be full - and `getQuota` is documented as reporting
31
+ // `null` for a provider that does not know.
32
+ getQuota: () => Promise.resolve(null),
33
+ }
34
+
35
+ export function sync(): Promise<boolean> {
36
+ return reject()
37
+ }
38
+
39
+ export function getAllItems(): Promise<Record<string, string>> {
40
+ return reject()
41
+ }