react-native-cloud-sync 0.3.0 → 0.5.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 (166) hide show
  1. package/README.md +116 -58
  2. package/ios/CloudSyncError.swift +21 -0
  3. package/ios/CloudSyncImpl.swift +515 -95
  4. package/ios/RNCloudSync.mm +73 -1
  5. package/jest-mock.js +1 -0
  6. package/lib/commonjs/hooks.js +309 -3
  7. package/lib/commonjs/hooks.js.map +1 -1
  8. package/lib/commonjs/internal/autoFlush.js +10 -1
  9. package/lib/commonjs/internal/autoFlush.js.map +1 -1
  10. package/lib/commonjs/internal/base64.js +25 -5
  11. package/lib/commonjs/internal/base64.js.map +1 -1
  12. package/lib/commonjs/internal/cloudKitRest.js +91 -15
  13. package/lib/commonjs/internal/cloudKitRest.js.map +1 -1
  14. package/lib/commonjs/internal/googleDriveRest.js +304 -38
  15. package/lib/commonjs/internal/googleDriveRest.js.map +1 -1
  16. package/lib/commonjs/internal/keys.js +34 -17
  17. package/lib/commonjs/internal/keys.js.map +1 -1
  18. package/lib/commonjs/internal/records.js +48 -0
  19. package/lib/commonjs/internal/records.js.map +1 -0
  20. package/lib/commonjs/providers/cloudKit.js +85 -17
  21. package/lib/commonjs/providers/cloudKit.js.map +1 -1
  22. package/lib/commonjs/providers/cloudKitEncrypted.js +30 -7
  23. package/lib/commonjs/providers/cloudKitEncrypted.js.map +1 -1
  24. package/lib/commonjs/providers/googleDrive.js +37 -2
  25. package/lib/commonjs/providers/googleDrive.js.map +1 -1
  26. package/lib/commonjs/providers/icloudDocuments.js +27 -0
  27. package/lib/commonjs/providers/icloudDocuments.js.map +1 -1
  28. package/lib/commonjs/providers/icloudKV.js +13 -3
  29. package/lib/commonjs/providers/icloudKV.js.map +1 -1
  30. package/lib/commonjs/providers/icloudKV.web.js +8 -1
  31. package/lib/commonjs/providers/icloudKV.web.js.map +1 -1
  32. package/lib/commonjs/providers/memory.js +10 -0
  33. package/lib/commonjs/providers/memory.js.map +1 -1
  34. package/lib/commonjs/resolvers.js +27 -13
  35. package/lib/commonjs/resolvers.js.map +1 -1
  36. package/lib/commonjs/specs/NativeRNCloudSync.js +3 -0
  37. package/lib/commonjs/specs/NativeRNCloudSync.js.map +1 -1
  38. package/lib/commonjs/store.js +360 -173
  39. package/lib/commonjs/store.js.map +1 -1
  40. package/lib/commonjs/types.js.map +1 -1
  41. package/lib/module/hooks.js +307 -3
  42. package/lib/module/hooks.js.map +1 -1
  43. package/lib/module/index.js +2 -2
  44. package/lib/module/internal/autoFlush.js +10 -1
  45. package/lib/module/internal/autoFlush.js.map +1 -1
  46. package/lib/module/internal/base64.js +25 -5
  47. package/lib/module/internal/base64.js.map +1 -1
  48. package/lib/module/internal/cloudKitRest.js +89 -13
  49. package/lib/module/internal/cloudKitRest.js.map +1 -1
  50. package/lib/module/internal/googleDriveRest.js +304 -38
  51. package/lib/module/internal/googleDriveRest.js.map +1 -1
  52. package/lib/module/internal/keys.js +33 -17
  53. package/lib/module/internal/keys.js.map +1 -1
  54. package/lib/module/internal/records.js +41 -0
  55. package/lib/module/internal/records.js.map +1 -0
  56. package/lib/module/providers/cloudKit.js +86 -18
  57. package/lib/module/providers/cloudKit.js.map +1 -1
  58. package/lib/module/providers/cloudKitEncrypted.js +31 -8
  59. package/lib/module/providers/cloudKitEncrypted.js.map +1 -1
  60. package/lib/module/providers/googleDrive.js +37 -2
  61. package/lib/module/providers/googleDrive.js.map +1 -1
  62. package/lib/module/providers/icloudDocuments.js +28 -1
  63. package/lib/module/providers/icloudDocuments.js.map +1 -1
  64. package/lib/module/providers/icloudKV.js +13 -3
  65. package/lib/module/providers/icloudKV.js.map +1 -1
  66. package/lib/module/providers/icloudKV.web.js +8 -1
  67. package/lib/module/providers/icloudKV.web.js.map +1 -1
  68. package/lib/module/providers/memory.js +10 -0
  69. package/lib/module/providers/memory.js.map +1 -1
  70. package/lib/module/resolvers.js +27 -12
  71. package/lib/module/resolvers.js.map +1 -1
  72. package/lib/module/specs/NativeRNCloudSync.js +4 -0
  73. package/lib/module/specs/NativeRNCloudSync.js.map +1 -1
  74. package/lib/module/store.js +360 -173
  75. package/lib/module/store.js.map +1 -1
  76. package/lib/module/types.js.map +1 -1
  77. package/lib/typescript/commonjs/errors.d.ts +16 -16
  78. package/lib/typescript/commonjs/errors.d.ts.map +1 -1
  79. package/lib/typescript/commonjs/hooks.d.ts +68 -0
  80. package/lib/typescript/commonjs/hooks.d.ts.map +1 -1
  81. package/lib/typescript/commonjs/index.d.ts +2 -2
  82. package/lib/typescript/commonjs/internal/autoFlush.d.ts.map +1 -1
  83. package/lib/typescript/commonjs/internal/base64.d.ts.map +1 -1
  84. package/lib/typescript/commonjs/internal/cloudKitRest.d.ts +20 -0
  85. package/lib/typescript/commonjs/internal/cloudKitRest.d.ts.map +1 -1
  86. package/lib/typescript/commonjs/internal/googleDriveRest.d.ts +19 -0
  87. package/lib/typescript/commonjs/internal/googleDriveRest.d.ts.map +1 -1
  88. package/lib/typescript/commonjs/internal/keys.d.ts +18 -3
  89. package/lib/typescript/commonjs/internal/keys.d.ts.map +1 -1
  90. package/lib/typescript/commonjs/internal/records.d.ts +24 -0
  91. package/lib/typescript/commonjs/internal/records.d.ts.map +1 -0
  92. package/lib/typescript/commonjs/providers/cloudKit.d.ts +1 -1
  93. package/lib/typescript/commonjs/providers/cloudKit.d.ts.map +1 -1
  94. package/lib/typescript/commonjs/providers/cloudKitBackup.d.ts +1 -1
  95. package/lib/typescript/commonjs/providers/cloudKitBackup.d.ts.map +1 -1
  96. package/lib/typescript/commonjs/providers/cloudKitEncrypted.d.ts.map +1 -1
  97. package/lib/typescript/commonjs/providers/googleDrive.d.ts.map +1 -1
  98. package/lib/typescript/commonjs/providers/googleDriveFiles.d.ts.map +1 -1
  99. package/lib/typescript/commonjs/providers/icloudDocuments.d.ts +1 -1
  100. package/lib/typescript/commonjs/providers/icloudDocuments.d.ts.map +1 -1
  101. package/lib/typescript/commonjs/providers/icloudKV.d.ts.map +1 -1
  102. package/lib/typescript/commonjs/providers/icloudKV.web.d.ts.map +1 -1
  103. package/lib/typescript/commonjs/providers/memory.d.ts.map +1 -1
  104. package/lib/typescript/commonjs/resolvers.d.ts +6 -3
  105. package/lib/typescript/commonjs/resolvers.d.ts.map +1 -1
  106. package/lib/typescript/commonjs/specs/NativeRNCloudSync.d.ts +12 -3
  107. package/lib/typescript/commonjs/specs/NativeRNCloudSync.d.ts.map +1 -1
  108. package/lib/typescript/commonjs/store.d.ts.map +1 -1
  109. package/lib/typescript/commonjs/types.d.ts +31 -3
  110. package/lib/typescript/commonjs/types.d.ts.map +1 -1
  111. package/lib/typescript/module/errors.d.ts +16 -16
  112. package/lib/typescript/module/errors.d.ts.map +1 -1
  113. package/lib/typescript/module/hooks.d.ts +68 -0
  114. package/lib/typescript/module/hooks.d.ts.map +1 -1
  115. package/lib/typescript/module/index.d.ts +2 -2
  116. package/lib/typescript/module/internal/autoFlush.d.ts.map +1 -1
  117. package/lib/typescript/module/internal/base64.d.ts.map +1 -1
  118. package/lib/typescript/module/internal/cloudKitRest.d.ts +20 -0
  119. package/lib/typescript/module/internal/cloudKitRest.d.ts.map +1 -1
  120. package/lib/typescript/module/internal/googleDriveRest.d.ts +19 -0
  121. package/lib/typescript/module/internal/googleDriveRest.d.ts.map +1 -1
  122. package/lib/typescript/module/internal/keys.d.ts +18 -3
  123. package/lib/typescript/module/internal/keys.d.ts.map +1 -1
  124. package/lib/typescript/module/internal/records.d.ts +24 -0
  125. package/lib/typescript/module/internal/records.d.ts.map +1 -0
  126. package/lib/typescript/module/providers/cloudKit.d.ts +1 -1
  127. package/lib/typescript/module/providers/cloudKit.d.ts.map +1 -1
  128. package/lib/typescript/module/providers/cloudKitBackup.d.ts +1 -1
  129. package/lib/typescript/module/providers/cloudKitBackup.d.ts.map +1 -1
  130. package/lib/typescript/module/providers/cloudKitEncrypted.d.ts.map +1 -1
  131. package/lib/typescript/module/providers/googleDrive.d.ts.map +1 -1
  132. package/lib/typescript/module/providers/googleDriveFiles.d.ts.map +1 -1
  133. package/lib/typescript/module/providers/icloudDocuments.d.ts +1 -1
  134. package/lib/typescript/module/providers/icloudDocuments.d.ts.map +1 -1
  135. package/lib/typescript/module/providers/icloudKV.d.ts.map +1 -1
  136. package/lib/typescript/module/providers/icloudKV.web.d.ts.map +1 -1
  137. package/lib/typescript/module/providers/memory.d.ts.map +1 -1
  138. package/lib/typescript/module/resolvers.d.ts +6 -3
  139. package/lib/typescript/module/resolvers.d.ts.map +1 -1
  140. package/lib/typescript/module/specs/NativeRNCloudSync.d.ts +12 -3
  141. package/lib/typescript/module/specs/NativeRNCloudSync.d.ts.map +1 -1
  142. package/lib/typescript/module/store.d.ts.map +1 -1
  143. package/lib/typescript/module/types.d.ts +31 -3
  144. package/lib/typescript/module/types.d.ts.map +1 -1
  145. package/package.json +36 -23
  146. package/plugin/build/index.js +45 -13
  147. package/react-native-cloud-sync.podspec +10 -3
  148. package/src/hooks.ts +357 -3
  149. package/src/index.ts +2 -2
  150. package/src/internal/autoFlush.ts +10 -1
  151. package/src/internal/base64.ts +26 -5
  152. package/src/internal/cloudKitRest.ts +103 -14
  153. package/src/internal/googleDriveRest.ts +338 -37
  154. package/src/internal/keys.ts +42 -16
  155. package/src/internal/records.ts +38 -0
  156. package/src/providers/cloudKit.ts +96 -20
  157. package/src/providers/cloudKitEncrypted.ts +37 -8
  158. package/src/providers/googleDrive.ts +38 -2
  159. package/src/providers/icloudDocuments.ts +40 -2
  160. package/src/providers/icloudKV.ts +13 -3
  161. package/src/providers/icloudKV.web.ts +8 -2
  162. package/src/providers/memory.ts +8 -0
  163. package/src/resolvers.ts +28 -13
  164. package/src/specs/NativeRNCloudSync.ts +16 -2
  165. package/src/store.ts +433 -190
  166. package/src/types.ts +32 -3
package/README.md CHANGED
@@ -13,7 +13,7 @@
13
13
  <h1 align="center">react-native-cloud-sync</h1>
14
14
 
15
15
  <p align="center">
16
- iCloud key-value store, CloudKit and Google Drive behind one API - iOS, Android, web, both architectures.
16
+ iCloud key-value store, CloudKit, iCloud Drive and Google Drive behind one API - iOS, Android, web, both architectures.
17
17
  </p>
18
18
 
19
19
  <p align="center">
@@ -23,35 +23,91 @@
23
23
  <a href="https://kesha-antonov.github.io/react-native-cloud-sync/platform-notes">Platform Notes</a>
24
24
  </p>
25
25
 
26
- ---
26
+ <p align="center">
27
+ <img src="assets/sync-demo.gif" width="760" alt="A book saved on an iPhone syncs through iCloud to an iPad and a Mac and through Google Drive to an Android phone and the web, then un-saved on Android it syncs back everywhere" />
28
+ </p>
29
+
30
+ <p align="center">
31
+ <sub>Using it in production? A ⭐ helps other developers find the library.</sub>
32
+ </p>
33
+
34
+ <!-- cryptoc-promo:start -->
35
+ <hr />
36
+
37
+ <h2 align="center">Sponsors</h2>
38
+
39
+ <p align="center">
40
+ <a href="https://getstream.io/chat/sdk/react-native/?utm_source=github&utm_medium=sponsor&utm_campaign=keshaantonov&utm_term=react-native-cloud-sync"><img width="100" height="100" src="https://raw.githubusercontent.com/kesha-antonov/react-native-chat/main/media/getstream-sponsor-logo.png" alt="Stream" /></a>
41
+ <br />
42
+ <a href="https://getstream.io/chat/sdk/react-native/?utm_source=github&utm_medium=sponsor&utm_campaign=keshaantonov&utm_term=react-native-cloud-sync"><strong>Stream</strong></a> - React Native Chat SDK
43
+ </p>
44
+
45
+ <hr />
46
+
47
+ <table align="center">
48
+ <tr>
49
+ <td align="center" valign="top" width="190">
50
+ <a href="https://cryptoc-app.web.app/"><img src="https://cryptoc-app.web.app/img/icon.png?v=3" width="76" height="76" alt="cryptoc app icon" /></a>
51
+ <br /><br />
52
+ <img src="https://cryptoc-app.web.app/img/qr-get.png?v=2" width="124" height="124" alt="QR code that installs cryptoc" />
53
+ <br />
54
+ <sub>Scan to install</sub>
55
+ <br /><br />
56
+ <!-- App Store button hidden for now
57
+ <a href="https://apps.apple.com/app/cryptoc/id1333169178"><img height="40" src="https://cryptoc-app.web.app/img/appstore.svg?v=2" alt="Download on the App Store" /></a>
58
+ <br />
59
+ -->
60
+ <a href="https://play.google.com/store/apps/details?id=co.ssoul.CryptoC"><img height="59" src="https://cryptoc-app.web.app/img/googleplay.png?v=2" alt="Get it on Google Play" /></a>
61
+ </td>
62
+ <td valign="top">
63
+
64
+ ### Support my work
65
+
66
+ **[cryptoc](https://cryptoc-app.web.app/)** - my crypto portfolio app. Your coins on the home screen, lock screen and watch face. iPhone, iPad, Mac, Apple Watch, Android, Android tablet and Wear OS.
67
+
68
+ - Portfolio with average buy price and 24h / 180-day / all-time P&L
69
+ - Widgets in three sizes, refreshed in the background - most days you never open the app
70
+ - Price alerts on 5,000+ coins, delivered while the app is closed
71
+ - **No account, no email, no exchange API keys, no ads.** Your holdings never reach a server - they sync through your own iCloud or Google Drive
72
+ - Free for 3 holdings, and that is not a trial timer
73
+
74
+ <sub>This is the app the library was built for. Downloading it pays for the time that goes into maintaining it.</sub>
75
+
76
+ </td>
77
+ </tr>
78
+ </table>
79
+
80
+ <hr />
81
+ <!-- cryptoc-promo:end -->
27
82
 
28
83
  ## ✨ Features
29
84
 
30
- - ☁️ Four providers behind one API - [`NSUbiquitousKeyValueStore`][kvs] (Apple's small key-value iCloud store), [CloudKit][ck] records, [iCloud Drive][icdrive] documents, Google Drive [`appDataFolder`][appdata] - directly or through one facade.
31
- - 🍏 CloudKit reaches Android and web too, via [CloudKit Web Services][ckws] - the same [private database][ckdb] your iOS app uses.
32
- - 📂 `icloudDocuments` writes into the user's real iCloud Drive, visible in Files.app - unlike an invisible `CKAsset`.
85
+ - ☁️ Four providers behind one API: [`NSUbiquitousKeyValueStore`][kvs] (Apple's small key-value iCloud store), [CloudKit][ck] records, [iCloud Drive][icdrive] documents and Google Drive [`appDataFolder`][appdata]. Use them directly or through one facade.
86
+ - 🔄 Auto-sync between iOS and Android in **both directions**: `mirror` writes to iCloud and Drive together, `resolve` reads back whichever copy is newest, so either platform can be where the user started.
87
+ - 🍏 CloudKit reaches Android and web too, via [CloudKit Web Services][ckws], against the same [private database][ckdb] your iOS app uses.
88
+ - 📂 `icloudDocuments` writes into the user's own iCloud Drive, so the files show up in Files.app.
33
89
  - 🚨 Every failure is a typed rejection (`ERR_NOT_SIGNED_IN`, `ERR_QUOTA_EXCEEDED`, `ERR_RATE_LIMITED` with `retryAfterMs`, ...); `null` means only "key doesn't exist".
34
90
  - 👤 All five [`CKAccountStatus`][ckstatus] values surface as-is, plus `onAccountChange` with `identityChanged`, which drops the previous account's caches and queued writes.
35
91
  - 🔔 `onRemoteChange` fires on every provider and the facade, including Google Drive via its change cursor.
36
- - 📦 Small values go to the key-value store, larger ones to a [`CKRecord`][ckrecord] field, binary as a [`CKAsset`][ckasset] or a resumable Drive upload - sized automatically.
92
+ - 📦 Small values go to the key-value store, larger ones to a [`CKRecord`][ckrecord] field, binary to a [`CKAsset`][ckasset] or a resumable Drive upload. The size check picks the target.
37
93
  - 🔁 Retryable failures queue into a durable outbox: backoff honours retry hints, auto-drains on foreground, bounded, never overwrites a newer write.
38
94
  - 🧺 `multiGet`/`multiSet`/`multiRemove`/`clear` batch for real, one request per provider.
39
- - 🪝 React hooks - `useCloudItem`, `useAccountStatus`, `usePendingWrites` from `/hooks` - without the stale-response and unmounted-`setState` bugs.
40
- - 🔐 `cloudKitEncrypted` uses CloudKit's own `encryptedValues` - ciphertext only, no key exposed; elsewhere, a `codec` seam for your own cipher.
41
- - 🧪 An in-memory provider with fault injection, plus the native mock, both exported (`/testing`, `/jest-mock`) - every failure path testable in Jest.
42
- - ⚙️ React Native 0.71 through 0.86+, old and new architecture, with the `#ifdef` bridge to prove it.
95
+ - 🪝 React hooks from `/hooks`: `useCloudItem`, `useCloudItems`, `useCloudCollection`, `useAccountStatus`, `usePendingWrites`. They drop stale responses and never `setState` after unmount.
96
+ - 🔐 `cloudKitEncrypted` uses CloudKit's own `encryptedValues`, so only ciphertext leaves the device; every other provider has a `codec` seam for your own cipher.
97
+ - 🧪 An in-memory provider with fault injection, plus the native mock, both exported (`/testing`, `/jest-mock`), so every failure path is testable in Jest.
98
+ - ⚙️ React Native 0.71 through 0.86+, old and new architecture, with the `#ifdef` bridge for the legacy one.
43
99
 
44
100
  ## 💡 Why?
45
101
 
46
102
  Cloud storage in React Native is fragmented into single-provider wrappers repeating the same defects: two ship a `setItem` that **reports a failed write as a success** (one checks the wrong error variable, the other discards the result entirely), and a third flattens five iCloud account states into one boolean.
47
103
 
48
- A `catch { return null }` makes "not signed in", "offline", "out of storage" and "no such key" indistinguishable - apps can't tell the user anything useful, or decide whether to retry.
104
+ A `catch { return null }` makes "not signed in", "offline", "out of storage" and "no such key" indistinguishable. The app can't tell the user anything useful, or decide whether to retry.
49
105
 
50
- This library starts from the opposite end: the error contract first, providers second.
106
+ This library was built error contract first, providers second.
51
107
 
52
108
  ## 📚 Upstream documentation
53
109
 
54
- This package is a wrapper: unexpected behavior is usually explained in Apple's or Google's docs, not ours.
110
+ This package is a wrapper. When something behaves unexpectedly, the answer is usually in Apple's or Google's docs.
55
111
 
56
112
  **Apple**
57
113
 
@@ -72,7 +128,7 @@ This package is a wrapper: unexpected behavior is usually explained in Apple's o
72
128
  |---|---|
73
129
  | [The `appDataFolder`][appdata] | The hidden per-app folder this package stores into |
74
130
  | [Drive `files` resource][drivefiles] | The REST endpoints behind the provider |
75
- | [Drive API scopes][drivescopes] | Why `drive.appdata`, not something broader |
131
+ | [Drive API scopes][drivescopes] | Why the scope is `drive.appdata` |
76
132
 
77
133
  [kvs]: https://developer.apple.com/documentation/foundation/nsubiquitouskeyvaluestore
78
134
  [ck]: https://developer.apple.com/documentation/cloudkit
@@ -96,40 +152,40 @@ This package is a wrapper: unexpected behavior is usually explained in Apple's o
96
152
 
97
153
  | | **this** | [kuatsu/<br />cloud-storage][kuatsu] | [icloud-kit][ik] | [expo-cloudkit][ec] | [okwasniewski/<br />icloud-storage][ok] | [cloudkit-<br />storage][jp] |
98
154
  |---|:---:|:---:|:---:|:---:|:---:|:---:|
99
- | iCloud key-value store | ✅ | ✅ | ✅ | – | ✅ | – |
100
- | CloudKit records | ✅ | – | ✅ | ✅ | – | ✅ |
101
- | Google Drive | ✅ | ✅ | – | – | – | – |
155
+ | iCloud key-value store | ✅ | ✅ | ✅ | - | ✅ | - |
156
+ | CloudKit records | ✅ | - | ✅ | ✅ | - | ✅ |
157
+ | Google Drive | ✅ | ✅ | - | - | - | - |
102
158
  | iOS | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
103
- | Android | ✅ | ✅ | – | ❌ [[1]](#note-1) | – | – |
104
- | Web | ✅ | partial [[2]](#note-2) | – | – | – | – |
105
- | **CloudKit on Android/web** | ✅ | – | – | ❌ [[1]](#note-1) | – | – |
106
- | New Architecture | ✅ | ✅ | ✅ | ✅ | ✅ | – |
159
+ | Android | ✅ | ✅ | - | ❌ [[1]](#note-1) | - | - |
160
+ | Web | ✅ | partial [[2]](#note-2) | - | - | - | - |
161
+ | **CloudKit on Android/web** | ✅ | - | - | ❌ [[1]](#note-1) | - | - |
162
+ | New Architecture | ✅ | ✅ | ✅ | ✅ | ✅ | - |
107
163
  | **Legacy Architecture** | ✅ | ❌ | ✅ [[3]](#note-3) | ✅ [[3]](#note-3) | ✅ [[3]](#note-3) | ✅ |
108
- | Typed error codes | ✅ | – | partial | ✅ | – | – |
109
- | 5-value account status | ✅ | boolean | boolean | ✅ | – | – |
110
- | Identity-change event | ✅ | ⚠️ [[4]](#note-4) | – | ✅ | – | – |
111
- | Remote-change event | ✅ | ✅ | – | n/a | ❌ [[5]](#note-5) | ✅ |
112
- | Offline write queue | ✅ | – | – | ✅ | – | – |
113
- | Size tiering | ✅ | – | – | – | – | – |
114
- | Binary / assets | ✅ [[9]](#note-9) | ✅ | ❌ [[6]](#note-6) | ✅ | – | – |
115
- | User-visible iCloud Drive files | ✅ | – | – | – | ✅ | – |
116
- | Native end-to-end encryption | ✅ | – | – | – | – | – |
117
- | Batch operations | ✅ | – | – | – | – | – |
118
- | React hooks | ✅ | ✅ | – | – | – | – |
119
- | Encryption seam | ✅ | – | – | – | – | – |
120
- | Exported test harness | ✅ | – | – | ⚠️ [[7]](#note-7) | – | – |
121
- | Mac Catalyst | ✅ | – | – | ⚠️ | – | – |
164
+ | Typed error codes | ✅ | - | partial | ✅ | - | - |
165
+ | 5-value account status | ✅ | boolean | boolean | ✅ | - | - |
166
+ | Identity-change event | ✅ | ⚠️ [[4]](#note-4) | - | ✅ | - | - |
167
+ | Remote-change event | ✅ | ✅ | - | n/a | ❌ [[5]](#note-5) | ✅ |
168
+ | Offline write queue | ✅ | - | - | ✅ | - | - |
169
+ | Size tiering | ✅ | - | - | - | - | - |
170
+ | Binary / assets | ✅ [[9]](#note-9) | ✅ | ❌ [[6]](#note-6) | ✅ | - | - |
171
+ | User-visible iCloud Drive files | ✅ | - | - | - | ✅ | - |
172
+ | Native end-to-end encryption | ✅ | - | - | - | - | - |
173
+ | Batch operations | ✅ | - | - | - | - | - |
174
+ | React hooks | ✅ | ✅ | - | - | - | - |
175
+ | Encryption seam | ✅ | - | - | - | - | - |
176
+ | Exported test harness | ✅ | - | - | ⚠️ [[7]](#note-7) | - | - |
177
+ | Mac Catalyst | ✅ | - | - | ⚠️ | - | - |
122
178
  | Actively maintained | ✅ | ✅ | ✅ | ❌ [[8]](#note-8) | ❌ [[5]](#note-5) | ❌ |
123
179
 
124
180
  <a id="note-1"></a>**[1]** expo-cloudkit's README: Android throws `CloudKitNotSupportedError` on every call.
125
181
  <a id="note-2"></a>**[2]** Google Drive support is text-based only.
126
- <a id="note-3"></a>**[3]** Via the Expo Modules API - pulls in `expo-modules-core`.
127
- <a id="note-4"></a>**[4]** Fires before JS binds the emitter, crashing with `std::bad_function_call` (SIGABRT) - hit three times.
182
+ <a id="note-3"></a>**[3]** Via the Expo Modules API; pulls in `expo-modules-core`.
183
+ <a id="note-4"></a>**[4]** Fires before JS binds the emitter, crashing with `std::bad_function_call` (SIGABRT); hit three times.
128
184
  <a id="note-5"></a>**[5]** One version ever shipped; the change-listener PR has sat open since February.
129
- <a id="note-6"></a>**[6]** Field type is `string | number | null` - can't hold binary data.
185
+ <a id="note-6"></a>**[6]** Field type is `string | number | null`, so it can't hold binary data.
130
186
  <a id="note-7"></a>**[7]** A mock factory exists, but isn't exported or documented.
131
187
  <a id="note-8"></a>**[8]** No commits since April; the last four releases shipped with Swift that didn't compile.
132
- <a id="note-9"></a>**[9]** `CKAsset` on Apple platforms; CloudKit Web Services' upload-token protocol on Android/web, capped at 15 MB (CloudKit's limit, not this package's). Use [`googleDriveFiles`](https://kesha-antonov.github.io/react-native-cloud-sync/providers/google-drive#large-files) for anything bigger - it chunks and resumes the same way.
188
+ <a id="note-9"></a>**[9]** `CKAsset` on Apple platforms; CloudKit Web Services' upload-token protocol on Android/web, capped at 15 MB by CloudKit. Use [`googleDriveFiles`](https://kesha-antonov.github.io/react-native-cloud-sync/providers/google-drive#large-files) for anything bigger; it chunks and resumes the same way.
133
189
 
134
190
  [kuatsu]: https://github.com/kuatsu/react-native-cloud-storage
135
191
  [ik]: https://github.com/BogdanGeorgian91/react-native-icloud-kit
@@ -143,7 +199,7 @@ This package is a wrapper: unexpected behavior is usually explained in Apple's o
143
199
  |---|---|
144
200
  | [Choosing a provider](https://kesha-antonov.github.io/react-native-cloud-sync/choosing-a-provider) | Which one, what it costs, why to let the user pick |
145
201
  | [iCloud key-value store](https://kesha-antonov.github.io/react-native-cloud-sync/providers/icloud-kv) | Small settings, zero friction, Apple only |
146
- | [CloudKit](https://kesha-antonov.github.io/react-native-cloud-sync/providers/cloudkit) | Records, zones, assets - and the Android/web path |
202
+ | [CloudKit](https://kesha-antonov.github.io/react-native-cloud-sync/providers/cloudkit) | Records, zones, assets, and the Android/web path |
147
203
  | [iCloud Drive](https://kesha-antonov.github.io/react-native-cloud-sync/providers/icloud-drive) | Files in the user's own Drive, visible in Files.app |
148
204
  | [Google Drive](https://kesha-antonov.github.io/react-native-cloud-sync/providers/google-drive) | The always-on cross-platform backend |
149
205
  | [The store facade](https://kesha-antonov.github.io/react-native-cloud-sync/store) | Tiering, outbox, migration, fallthrough |
@@ -170,13 +226,13 @@ Both architectures supported; RN 0.82 removed Legacy Architecture, so that half
170
226
 
171
227
  | | iOS / macOS | Android | Web |
172
228
  |---|:---:|:---:|:---:|
173
- | `icloudKV` | native | – | – |
229
+ | `icloudKV` | native | - | - |
174
230
  | `cloudKit` | native | REST | REST |
175
- | `cloudKitEncrypted` | native | – | – |
176
- | `icloudDocuments` | native | – | – |
231
+ | `cloudKitEncrypted` | native | - | - |
232
+ | `icloudDocuments` | native | - | - |
177
233
  | `googleDrive` | REST | REST | REST |
178
234
 
179
- An unavailable provider rejects with `ERR_UNSUPPORTED_PLATFORM` rather than silently no-op'ing - [Choosing a provider](https://kesha-antonov.github.io/react-native-cloud-sync/choosing-a-provider) covers the trade-offs.
235
+ An unavailable provider rejects with `ERR_UNSUPPORTED_PLATFORM` instead of silently doing nothing. [Choosing a provider](https://kesha-antonov.github.io/react-native-cloud-sync/choosing-a-provider) covers the trade-offs.
180
236
 
181
237
  ## 📦 Installation
182
238
 
@@ -204,7 +260,7 @@ Bare React Native and manual `ios/` entitlement keys: see [Installation](https:/
204
260
 
205
261
  ### iCloud key-value store
206
262
 
207
- No sign-in, no UI - uses the device's existing account.
263
+ No sign-in and no UI; it uses the device's existing account.
208
264
 
209
265
  ```ts
210
266
  import { icloudKV } from 'react-native-cloud-sync'
@@ -216,7 +272,7 @@ const theme = await icloudKV.getItem('settings/theme')
216
272
  icloudKV.onRemoteChange(({ keys }) => reload(keys))
217
273
  ```
218
274
 
219
- [Full guide →](https://kesha-antonov.github.io/react-native-cloud-sync/providers/icloud-kv)
275
+ [Full guide](https://kesha-antonov.github.io/react-native-cloud-sync/providers/icloud-kv)
220
276
 
221
277
  ### CloudKit
222
278
 
@@ -232,11 +288,11 @@ const raw = await cloudKit.getItem('playlist')
232
288
  await cloudKitAssets.save({ recordName: 'avatar', fieldName: 'image', fileUri })
233
289
  ```
234
290
 
235
- Android/web needs an Apple ID sign-in whose token lasts up to two weeks - an explicit import, not background sync. [Full guide →](https://kesha-antonov.github.io/react-native-cloud-sync/providers/cloudkit)
291
+ Android/web needs an Apple ID sign-in, and that token lasts up to two weeks, which suits an explicit import rather than background sync. [Full guide](https://kesha-antonov.github.io/react-native-cloud-sync/providers/cloudkit)
236
292
 
237
293
  ### Sensitive data
238
294
 
239
- CloudKit's own end-to-end encryption - Apple stores ciphertext and holds no key.
295
+ CloudKit's own end-to-end encryption: Apple stores ciphertext and holds no key.
240
296
 
241
297
  ```ts
242
298
  import { cloudKitEncrypted } from 'react-native-cloud-sync'
@@ -244,11 +300,11 @@ import { cloudKitEncrypted } from 'react-native-cloud-sync'
244
300
  await cloudKitEncrypted.setItem('auth.refreshToken', token)
245
301
  ```
246
302
 
247
- Apple-only: the key lives in the user's iCloud Keychain, so nothing server-side can decrypt it. Cross-platform needs the store's `codec` seam instead. [Full guide →](https://kesha-antonov.github.io/react-native-cloud-sync/encryption)
303
+ Apple-only: the key lives in the user's iCloud Keychain, so nothing server-side can decrypt it. Cross-platform needs the store's `codec` seam instead. [Full guide](https://kesha-antonov.github.io/react-native-cloud-sync/encryption)
248
304
 
249
305
  ### iCloud Drive
250
306
 
251
- Files the user can open in Files.app - not hidden in a private database.
307
+ Files the user can open in Files.app.
252
308
 
253
309
  ```ts
254
310
  import { icloudDocuments } from 'react-native-cloud-sync'
@@ -259,7 +315,7 @@ await icloudDocuments.save({ fileUri: localPath, name: 'Export 2024.csv' })
259
315
  const path = await icloudDocuments.fetch({ name: 'Export 2024.csv' })
260
316
  ```
261
317
 
262
- [Full guide →](https://kesha-antonov.github.io/react-native-cloud-sync/providers/icloud-drive)
318
+ [Full guide](https://kesha-antonov.github.io/react-native-cloud-sync/providers/icloud-drive)
263
319
 
264
320
  ### Google Drive
265
321
 
@@ -275,7 +331,7 @@ configureGoogleDrive({
275
331
  await googleDrive.setItem('playlist.json', JSON.stringify(tracks))
276
332
  ```
277
333
 
278
- [Full guide →](https://kesha-antonov.github.io/react-native-cloud-sync/providers/google-drive)
334
+ [Full guide](https://kesha-antonov.github.io/react-native-cloud-sync/providers/google-drive)
279
335
 
280
336
  ### All of them at once
281
337
 
@@ -284,8 +340,8 @@ import { createCloudStore } from 'react-native-cloud-sync'
284
340
 
285
341
  const store = createCloudStore({
286
342
  providers: ['icloudKV', 'googleDrive'], // preference order
287
- writeMode: 'mirror', // write to BOTH, not just the first
288
- resolve: resolveByTimestamp('updatedAt'), // read the newest, not the first
343
+ writeMode: 'mirror', // write to both providers, not only the preferred one
344
+ resolve: resolveByTimestamp('updatedAt'), // read whichever copy is newest
289
345
  tiering: 'auto', // route by size
290
346
  outboxStorage: mmkvAdapter, // survive restarts
291
347
  })
@@ -294,7 +350,7 @@ await store.setItem('playlist', json)
294
350
  await store.flushOutbox() // on reconnect
295
351
  ```
296
352
 
297
- Those two options make sync work in **both** directions across a mixed fleet: `mirror` copies to Drive so non-Apple devices can read it; `resolve` stops an Apple device serving a stale iCloud copy without checking Drive. Either platform can be where the user started. [Full guide →](https://kesha-antonov.github.io/react-native-cloud-sync/store)
353
+ Those two options make sync work in **both** directions across a mixed fleet: `mirror` copies to Drive so non-Apple devices can read it; `resolve` stops an Apple device serving a stale iCloud copy without checking Drive. [Full guide](https://kesha-antonov.github.io/react-native-cloud-sync/store)
298
354
 
299
355
  ### In a component
300
356
 
@@ -304,7 +360,7 @@ import { useCloudItem } from 'react-native-cloud-sync/hooks'
304
360
  const { value, setValue, loading, error } = useCloudItem<Settings>(store, 'settings')
305
361
  ```
306
362
 
307
- Re-reads on remote writes, drops stale responses, never calls `setState` after unmount. [Full guide →](https://kesha-antonov.github.io/react-native-cloud-sync/hooks)
363
+ Re-reads on remote writes, drops stale responses, never calls `setState` after unmount. [Full guide](https://kesha-antonov.github.io/react-native-cloud-sync/hooks)
308
364
 
309
365
  ### Handling failures
310
366
 
@@ -319,7 +375,7 @@ try {
319
375
  }
320
376
  ```
321
377
 
322
- [Full guide →](https://kesha-antonov.github.io/react-native-cloud-sync/errors)
378
+ [Full guide](https://kesha-antonov.github.io/react-native-cloud-sync/errors)
323
379
 
324
380
  ## 🧪 Testing
325
381
 
@@ -334,7 +390,7 @@ const provider = createMemoryProvider({
334
390
  provider.emitAccountChange({ status: 'available', identityChanged: true })
335
391
  ```
336
392
 
337
- Signed-out, offline and account-switch paths, all in Jest without a device. [Full guide →](https://kesha-antonov.github.io/react-native-cloud-sync/testing)
393
+ Signed-out, offline and account-switch paths, all in Jest without a device. [Full guide](https://kesha-antonov.github.io/react-native-cloud-sync/testing)
338
394
 
339
395
  ## 🧪 Example App
340
396
 
@@ -360,6 +416,8 @@ Issues and pull requests welcome. Run `yarn lint`, `yarn typecheck` and `yarn te
360
416
 
361
417
  - [Kesha Antonov](https://github.com/kesha-antonov)
362
418
 
419
+ I also build **[cryptoc](https://cryptoc-app.web.app/)** - a crypto portfolio app with home screen, lock screen and Watch widgets, no account and no exchange API keys. It is where this library came from.
420
+
363
421
  ## 📄 License
364
422
 
365
423
  MIT
@@ -69,6 +69,21 @@ enum CloudSyncError: Error {
69
69
  /// (or into `nil`) is what makes a signed-out user indistinguishable from an
70
70
  /// empty backup, which is the defect this whole package exists to avoid.
71
71
  static func fromCKError(_ error: CKError) -> CloudSyncError {
72
+ // A single-item CKModifyRecordsOperation / CKFetchRecordsOperation
73
+ // reports a per-record failure at the operation level wrapped in
74
+ // `.partialFailure`. Mapping the wrapper fell through to ERR_UNKNOWN,
75
+ // so a quota, size-limit, permission or conflict failure on a write
76
+ // lost its code (and its retryAfter / serverValue) on the way to JS.
77
+ if error.code == .partialFailure,
78
+ let underlying = error.partialErrorsByItemID?.values
79
+ .compactMap({ $0 as? CKError })
80
+ // Batch siblings fail with .batchRequestFailed; the real cause
81
+ // is the other one.
82
+ .first(where: { $0.code != .batchRequestFailed })
83
+ ?? error.partialErrorsByItemID?.values.compactMap({ $0 as? CKError }).first {
84
+ return fromCKError(underlying)
85
+ }
86
+
72
87
  var info: [String: Any] = [:]
73
88
  if let retryAfter = error.userInfo[CKErrorRetryAfterKey] as? Double {
74
89
  info["retryAfterMs"] = retryAfter * 1000
@@ -81,6 +96,12 @@ enum CloudSyncError: Error {
81
96
  message: "No iCloud account is signed in on this device.",
82
97
  info: info
83
98
  )
99
+ case .accountTemporarilyUnavailable:
100
+ return .coded(
101
+ code: CloudSyncErrorCode.accountUnavailable,
102
+ message: "The iCloud account is temporarily unavailable.",
103
+ info: info
104
+ )
84
105
  case .managedAccountRestricted, .permissionFailure:
85
106
  return .coded(
86
107
  code: CloudSyncErrorCode.accountRestricted,