react-native-cloud-sync 0.4.0 โ†’ 0.5.1

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 (160) hide show
  1. package/README.md +75 -86
  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 +73 -9
  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 +73 -9
  42. package/lib/module/hooks.js.map +1 -1
  43. package/lib/module/internal/autoFlush.js +10 -1
  44. package/lib/module/internal/autoFlush.js.map +1 -1
  45. package/lib/module/internal/base64.js +25 -5
  46. package/lib/module/internal/base64.js.map +1 -1
  47. package/lib/module/internal/cloudKitRest.js +89 -13
  48. package/lib/module/internal/cloudKitRest.js.map +1 -1
  49. package/lib/module/internal/googleDriveRest.js +304 -38
  50. package/lib/module/internal/googleDriveRest.js.map +1 -1
  51. package/lib/module/internal/keys.js +33 -17
  52. package/lib/module/internal/keys.js.map +1 -1
  53. package/lib/module/internal/records.js +41 -0
  54. package/lib/module/internal/records.js.map +1 -0
  55. package/lib/module/providers/cloudKit.js +86 -18
  56. package/lib/module/providers/cloudKit.js.map +1 -1
  57. package/lib/module/providers/cloudKitEncrypted.js +31 -8
  58. package/lib/module/providers/cloudKitEncrypted.js.map +1 -1
  59. package/lib/module/providers/googleDrive.js +37 -2
  60. package/lib/module/providers/googleDrive.js.map +1 -1
  61. package/lib/module/providers/icloudDocuments.js +28 -1
  62. package/lib/module/providers/icloudDocuments.js.map +1 -1
  63. package/lib/module/providers/icloudKV.js +13 -3
  64. package/lib/module/providers/icloudKV.js.map +1 -1
  65. package/lib/module/providers/icloudKV.web.js +8 -1
  66. package/lib/module/providers/icloudKV.web.js.map +1 -1
  67. package/lib/module/providers/memory.js +10 -0
  68. package/lib/module/providers/memory.js.map +1 -1
  69. package/lib/module/resolvers.js +27 -12
  70. package/lib/module/resolvers.js.map +1 -1
  71. package/lib/module/specs/NativeRNCloudSync.js +4 -0
  72. package/lib/module/specs/NativeRNCloudSync.js.map +1 -1
  73. package/lib/module/store.js +360 -173
  74. package/lib/module/store.js.map +1 -1
  75. package/lib/module/types.js.map +1 -1
  76. package/lib/typescript/commonjs/errors.d.ts +16 -16
  77. package/lib/typescript/commonjs/errors.d.ts.map +1 -1
  78. package/lib/typescript/commonjs/hooks.d.ts.map +1 -1
  79. package/lib/typescript/commonjs/internal/autoFlush.d.ts.map +1 -1
  80. package/lib/typescript/commonjs/internal/base64.d.ts.map +1 -1
  81. package/lib/typescript/commonjs/internal/cloudKitRest.d.ts +20 -0
  82. package/lib/typescript/commonjs/internal/cloudKitRest.d.ts.map +1 -1
  83. package/lib/typescript/commonjs/internal/googleDriveRest.d.ts +19 -0
  84. package/lib/typescript/commonjs/internal/googleDriveRest.d.ts.map +1 -1
  85. package/lib/typescript/commonjs/internal/keys.d.ts +18 -3
  86. package/lib/typescript/commonjs/internal/keys.d.ts.map +1 -1
  87. package/lib/typescript/commonjs/internal/records.d.ts +24 -0
  88. package/lib/typescript/commonjs/internal/records.d.ts.map +1 -0
  89. package/lib/typescript/commonjs/providers/cloudKit.d.ts +1 -1
  90. package/lib/typescript/commonjs/providers/cloudKit.d.ts.map +1 -1
  91. package/lib/typescript/commonjs/providers/cloudKitBackup.d.ts +1 -1
  92. package/lib/typescript/commonjs/providers/cloudKitBackup.d.ts.map +1 -1
  93. package/lib/typescript/commonjs/providers/cloudKitEncrypted.d.ts.map +1 -1
  94. package/lib/typescript/commonjs/providers/googleDrive.d.ts.map +1 -1
  95. package/lib/typescript/commonjs/providers/googleDriveFiles.d.ts.map +1 -1
  96. package/lib/typescript/commonjs/providers/icloudDocuments.d.ts +1 -1
  97. package/lib/typescript/commonjs/providers/icloudDocuments.d.ts.map +1 -1
  98. package/lib/typescript/commonjs/providers/icloudKV.d.ts.map +1 -1
  99. package/lib/typescript/commonjs/providers/icloudKV.web.d.ts.map +1 -1
  100. package/lib/typescript/commonjs/providers/memory.d.ts.map +1 -1
  101. package/lib/typescript/commonjs/resolvers.d.ts +6 -3
  102. package/lib/typescript/commonjs/resolvers.d.ts.map +1 -1
  103. package/lib/typescript/commonjs/specs/NativeRNCloudSync.d.ts +12 -3
  104. package/lib/typescript/commonjs/specs/NativeRNCloudSync.d.ts.map +1 -1
  105. package/lib/typescript/commonjs/store.d.ts.map +1 -1
  106. package/lib/typescript/commonjs/types.d.ts +31 -3
  107. package/lib/typescript/commonjs/types.d.ts.map +1 -1
  108. package/lib/typescript/module/errors.d.ts +16 -16
  109. package/lib/typescript/module/errors.d.ts.map +1 -1
  110. package/lib/typescript/module/hooks.d.ts.map +1 -1
  111. package/lib/typescript/module/internal/autoFlush.d.ts.map +1 -1
  112. package/lib/typescript/module/internal/base64.d.ts.map +1 -1
  113. package/lib/typescript/module/internal/cloudKitRest.d.ts +20 -0
  114. package/lib/typescript/module/internal/cloudKitRest.d.ts.map +1 -1
  115. package/lib/typescript/module/internal/googleDriveRest.d.ts +19 -0
  116. package/lib/typescript/module/internal/googleDriveRest.d.ts.map +1 -1
  117. package/lib/typescript/module/internal/keys.d.ts +18 -3
  118. package/lib/typescript/module/internal/keys.d.ts.map +1 -1
  119. package/lib/typescript/module/internal/records.d.ts +24 -0
  120. package/lib/typescript/module/internal/records.d.ts.map +1 -0
  121. package/lib/typescript/module/providers/cloudKit.d.ts +1 -1
  122. package/lib/typescript/module/providers/cloudKit.d.ts.map +1 -1
  123. package/lib/typescript/module/providers/cloudKitBackup.d.ts +1 -1
  124. package/lib/typescript/module/providers/cloudKitBackup.d.ts.map +1 -1
  125. package/lib/typescript/module/providers/cloudKitEncrypted.d.ts.map +1 -1
  126. package/lib/typescript/module/providers/googleDrive.d.ts.map +1 -1
  127. package/lib/typescript/module/providers/googleDriveFiles.d.ts.map +1 -1
  128. package/lib/typescript/module/providers/icloudDocuments.d.ts +1 -1
  129. package/lib/typescript/module/providers/icloudDocuments.d.ts.map +1 -1
  130. package/lib/typescript/module/providers/icloudKV.d.ts.map +1 -1
  131. package/lib/typescript/module/providers/icloudKV.web.d.ts.map +1 -1
  132. package/lib/typescript/module/providers/memory.d.ts.map +1 -1
  133. package/lib/typescript/module/resolvers.d.ts +6 -3
  134. package/lib/typescript/module/resolvers.d.ts.map +1 -1
  135. package/lib/typescript/module/specs/NativeRNCloudSync.d.ts +12 -3
  136. package/lib/typescript/module/specs/NativeRNCloudSync.d.ts.map +1 -1
  137. package/lib/typescript/module/store.d.ts.map +1 -1
  138. package/lib/typescript/module/types.d.ts +31 -3
  139. package/lib/typescript/module/types.d.ts.map +1 -1
  140. package/package.json +38 -28
  141. package/plugin/build/index.js +45 -13
  142. package/react-native-cloud-sync.podspec +10 -3
  143. package/src/hooks.ts +69 -9
  144. package/src/internal/autoFlush.ts +10 -1
  145. package/src/internal/base64.ts +26 -5
  146. package/src/internal/cloudKitRest.ts +103 -14
  147. package/src/internal/googleDriveRest.ts +338 -37
  148. package/src/internal/keys.ts +42 -16
  149. package/src/internal/records.ts +38 -0
  150. package/src/providers/cloudKit.ts +96 -20
  151. package/src/providers/cloudKitEncrypted.ts +37 -8
  152. package/src/providers/googleDrive.ts +38 -2
  153. package/src/providers/icloudDocuments.ts +40 -2
  154. package/src/providers/icloudKV.ts +13 -3
  155. package/src/providers/icloudKV.web.ts +8 -2
  156. package/src/providers/memory.ts +8 -0
  157. package/src/resolvers.ts +28 -13
  158. package/src/specs/NativeRNCloudSync.ts +16 -2
  159. package/src/store.ts +433 -190
  160. package/src/types.ts +32 -3
package/README.md CHANGED
@@ -17,79 +17,68 @@
17
17
  </p>
18
18
 
19
19
  <p align="center">
20
- <a href="https://kesha-antonov.github.io/react-native-cloud-sync/">Documentation</a> ยท
21
- <a href="https://kesha-antonov.github.io/react-native-cloud-sync/comparison">Comparison</a> ยท
22
- <a href="https://kesha-antonov.github.io/react-native-cloud-sync/api">API</a> ยท
23
- <a href="https://kesha-antonov.github.io/react-native-cloud-sync/platform-notes">Platform Notes</a>
20
+ <a href="https://kesha-antonov.com/react-native-cloud-sync/">Documentation</a> ยท
21
+ <a href="https://kesha-antonov.com/react-native-cloud-sync/comparison">Comparison</a> ยท
22
+ <a href="https://kesha-antonov.com/react-native-cloud-sync/api">API</a> ยท
23
+ <a href="https://kesha-antonov.com/react-native-cloud-sync/platform-notes">Platform Notes</a>
24
24
  </p>
25
25
 
26
+ <!-- author:start -->
26
27
  <p align="center">
27
- <sub>Using it in production? A โญ helps other developers find the library.</sub>
28
+ <sub>Built and maintained by <a href="https://kesha-antonov.com">Kesha Antonov</a>, React Native lead engineer, <a href="https://kesha-antonov.com/react-native-developer/">available for hire</a>. More libraries, apps and case studies on <a href="https://kesha-antonov.com">kesha-antonov.com</a>.</sub>
28
29
  </p>
30
+ <!-- author:end -->
29
31
 
30
- <hr />
31
-
32
- <table align="center">
33
- <tr>
34
- <td align="center" valign="top" width="190">
35
- <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>
36
- <br /><br />
37
- <img src="https://cryptoc-app.web.app/img/qr-get.png?v=2" width="124" height="124" alt="QR code that installs cryptoc" />
38
- <br />
39
- <sub>Scan to install</sub>
40
- <br /><br />
41
- <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>
42
- <br />
43
- <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>
44
- </td>
45
- <td valign="top">
46
-
47
- ### Support my work
32
+ <p align="center">
33
+ <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" />
34
+ </p>
48
35
 
49
- **[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.
36
+ <p align="center">
37
+ <sub>Using it in production? A โญ helps other developers find the library.</sub>
38
+ </p>
50
39
 
51
- - Portfolio with average buy price and 24h / 180-day / all-time P&L
52
- - Widgets in three sizes, refreshed in the background - most days you never open the app
53
- - Price alerts on 5,000+ coins, delivered while the app is closed
54
- - **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
55
- - Free for 3 holdings, and that is not a trial timer
40
+ <!-- cryptoc-promo:start -->
41
+ <hr />
56
42
 
57
- <sub>This is the app the library was built for. Downloading it pays for the time that goes into maintaining it.</sub>
43
+ <h2 align="center">Sponsors</h2>
58
44
 
59
- </td>
60
- </tr>
61
- </table>
45
+ <p align="center">
46
+ <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>
47
+ <br />
48
+ <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
49
+ </p>
62
50
 
63
51
  <hr />
52
+ <!-- cryptoc-promo:end -->
64
53
 
65
54
  ## โœจ Features
66
55
 
67
- - โ˜๏ธ 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.
68
- - ๐Ÿ”„ 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.
69
- - ๐Ÿ CloudKit reaches Android and web too, via [CloudKit Web Services][ckws], against the same [private database][ckdb] your iOS app uses.
70
- - ๐Ÿ“‚ `icloudDocuments` writes into the user's own iCloud Drive, so the files show up in Files.app.
71
- - ๐Ÿšจ 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".
72
- - ๐Ÿ‘ค All five [`CKAccountStatus`][ckstatus] values surface as-is, plus `onAccountChange` with `identityChanged`, which drops the previous account's caches and queued writes.
73
- - ๐Ÿ”” `onRemoteChange` fires on every provider and the facade, including Google Drive via its change cursor.
74
- - ๐Ÿ“ฆ 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.
75
- - ๐Ÿ” Retryable failures queue into a durable outbox: backoff honours retry hints, auto-drains on foreground, bounded, never overwrites a newer write.
76
- - ๐Ÿงบ `multiGet`/`multiSet`/`multiRemove`/`clear` batch for real, one request per provider.
77
- - ๐Ÿช React hooks from `/hooks`: `useCloudItem`, `useCloudItems`, `useCloudCollection`, `useAccountStatus`, `usePendingWrites`. They drop stale responses and never `setState` after unmount.
78
- - ๐Ÿ” `cloudKitEncrypted` uses CloudKit's own `encryptedValues`, so only ciphertext leaves the device; every other provider has a `codec` seam for your own cipher.
79
- - ๐Ÿงช An in-memory provider with fault injection, plus the native mock, both exported (`/testing`, `/jest-mock`), so every failure path is testable in Jest.
80
- - โš™๏ธ React Native 0.71 through 0.86+, old and new architecture, with the `#ifdef` bridge for the legacy one.
56
+ - โ˜๏ธ Four providers, one API: [`NSUbiquitousKeyValueStore`][kvs] (iCloud key-value store), [CloudKit][ck] records, [iCloud Drive][icdrive] documents and Google Drive [`appDataFolder`][appdata]. Use each directly or through one facade.
57
+ - ๐Ÿ”„ Two-way sync between iOS and Android: `mirror` writes to iCloud and Drive together, `resolve` reads whichever copy is newest.
58
+ - ๐Ÿ CloudKit on Android and web via [CloudKit Web Services][ckws], against the same [private database][ckdb] as iOS.
59
+ - ๐Ÿ“‚ `icloudDocuments` writes to the user's iCloud Drive, visible in Files.app.
60
+ - ๐Ÿšจ Every failure is a typed rejection (`ERR_NOT_SIGNED_IN`, `ERR_QUOTA_EXCEEDED`, `ERR_RATE_LIMITED` with `retryAfterMs`, ...). `null` only means "key doesn't exist".
61
+ - ๐Ÿ‘ค All five [`CKAccountStatus`][ckstatus] values, plus `onAccountChange` with `identityChanged`, which drops the previous account's caches and queued writes.
62
+ - ๐Ÿ”” `onRemoteChange` on every provider and the facade, Google Drive included (via its change cursor).
63
+ - ๐Ÿ“ฆ Size tiering: 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.
64
+ - ๐Ÿ” Durable, bounded outbox for retryable failures: backoff honours retry hints, drains on foreground, never overwrites a newer write.
65
+ - ๐Ÿงบ Real batching: `multiGet`/`multiSet`/`multiRemove`/`clear` send one request per provider.
66
+ - ๐Ÿช Hooks from `/hooks`: `useCloudItem`, `useCloudItems`, `useCloudCollection`, `useAccountStatus`, `usePendingWrites`. Stale responses are dropped, no `setState` after unmount.
67
+ - ๐Ÿ” `cloudKitEncrypted` uses CloudKit `encryptedValues`, so only ciphertext leaves the device. Other providers take a `codec` for your own cipher.
68
+ - ๐Ÿงช Exported in-memory provider with fault injection and a native mock (`/testing`, `/jest-mock`): test every failure path in Jest.
69
+ - โš™๏ธ React Native 0.71 to 0.86+, old and new architecture.
81
70
 
82
71
  ## ๐Ÿ’ก Why?
83
72
 
84
- 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.
73
+ Existing React Native cloud storage libraries each wrap one provider and repeat the same defects. Two ship a `setItem` that **reports a failed write as success** (one checks the wrong error variable, the other ignores the result). A third flattens five iCloud account states into one boolean.
85
74
 
86
- 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.
75
+ A `catch { return null }` makes "not signed in", "offline", "out of storage" and "no such key" look the same, so the app can't tell the user what happened or decide whether to retry.
87
76
 
88
- This library was built error contract first, providers second.
77
+ This library starts from the error contract; providers come second.
89
78
 
90
79
  ## ๐Ÿ“š Upstream documentation
91
80
 
92
- This package is a wrapper. When something behaves unexpectedly, the answer is usually in Apple's or Google's docs.
81
+ This package is a wrapper. When something behaves unexpectedly, check Apple's or Google's docs.
93
82
 
94
83
  **Apple**
95
84
 
@@ -167,7 +156,7 @@ This package is a wrapper. When something behaves unexpectedly, the answer is us
167
156
  <a id="note-6"></a>**[6]** Field type is `string | number | null`, so it can't hold binary data.
168
157
  <a id="note-7"></a>**[7]** A mock factory exists, but isn't exported or documented.
169
158
  <a id="note-8"></a>**[8]** No commits since April; the last four releases shipped with Swift that didn't compile.
170
- <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.
159
+ <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.com/react-native-cloud-sync/providers/google-drive#large-files) for anything bigger; it chunks and resumes the same way.
171
160
 
172
161
  [kuatsu]: https://github.com/kuatsu/react-native-cloud-storage
173
162
  [ik]: https://github.com/BogdanGeorgian91/react-native-icloud-kit
@@ -179,20 +168,20 @@ This package is a wrapper. When something behaves unexpectedly, the answer is us
179
168
 
180
169
  | | |
181
170
  |---|---|
182
- | [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 |
183
- | [iCloud key-value store](https://kesha-antonov.github.io/react-native-cloud-sync/providers/icloud-kv) | Small settings, zero friction, Apple only |
184
- | [CloudKit](https://kesha-antonov.github.io/react-native-cloud-sync/providers/cloudkit) | Records, zones, assets, and the Android/web path |
185
- | [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 |
186
- | [Google Drive](https://kesha-antonov.github.io/react-native-cloud-sync/providers/google-drive) | The always-on cross-platform backend |
187
- | [The store facade](https://kesha-antonov.github.io/react-native-cloud-sync/store) | Tiering, outbox, migration, fallthrough |
188
- | [Error handling](https://kesha-antonov.github.io/react-native-cloud-sync/errors) | The typed contract |
189
- | [Encryption](https://kesha-antonov.github.io/react-native-cloud-sync/encryption) | What's encrypted for you, and how to add your own |
190
- | [React hooks](https://kesha-antonov.github.io/react-native-cloud-sync/hooks) | Binding cloud state to components |
191
- | [Recipes](https://kesha-antonov.github.io/react-native-cloud-sync/recipes) | Backup/restore, migration, offline-first |
192
- | [Testing](https://kesha-antonov.github.io/react-native-cloud-sync/testing) | Fault injection without a device |
193
- | [API reference](https://kesha-antonov.github.io/react-native-cloud-sync/api) | Every export |
194
- | [Platform notes](https://kesha-antonov.github.io/react-native-cloud-sync/platform-notes) | Entitlements, architectures, build config |
195
- | [Troubleshooting](https://kesha-antonov.github.io/react-native-cloud-sync/troubleshooting) | Common problems and what they usually mean |
171
+ | [Choosing a provider](https://kesha-antonov.com/react-native-cloud-sync/choosing-a-provider) | Which one, what it costs, why to let the user pick |
172
+ | [iCloud key-value store](https://kesha-antonov.com/react-native-cloud-sync/providers/icloud-kv) | Small settings, zero friction, Apple only |
173
+ | [CloudKit](https://kesha-antonov.com/react-native-cloud-sync/providers/cloudkit) | Records, zones, assets, and the Android/web path |
174
+ | [iCloud Drive](https://kesha-antonov.com/react-native-cloud-sync/providers/icloud-drive) | Files in the user's own Drive, visible in Files.app |
175
+ | [Google Drive](https://kesha-antonov.com/react-native-cloud-sync/providers/google-drive) | The always-on cross-platform backend |
176
+ | [The store facade](https://kesha-antonov.com/react-native-cloud-sync/store) | Tiering, outbox, migration, fallthrough |
177
+ | [Error handling](https://kesha-antonov.com/react-native-cloud-sync/errors) | The typed contract |
178
+ | [Encryption](https://kesha-antonov.com/react-native-cloud-sync/encryption) | What's encrypted for you, and how to add your own |
179
+ | [React hooks](https://kesha-antonov.com/react-native-cloud-sync/hooks) | Binding cloud state to components |
180
+ | [Recipes](https://kesha-antonov.com/react-native-cloud-sync/recipes) | Backup/restore, migration, offline-first |
181
+ | [Testing](https://kesha-antonov.com/react-native-cloud-sync/testing) | Fault injection without a device |
182
+ | [API reference](https://kesha-antonov.com/react-native-cloud-sync/api) | Every export |
183
+ | [Platform notes](https://kesha-antonov.com/react-native-cloud-sync/platform-notes) | Entitlements, architectures, build config |
184
+ | [Troubleshooting](https://kesha-antonov.com/react-native-cloud-sync/troubleshooting) | Common problems and what they usually mean |
196
185
 
197
186
  ## ๐Ÿ“‹ Requirements
198
187
 
@@ -202,7 +191,7 @@ This package is a wrapper. When something behaves unexpectedly, the answer is us
202
191
  | iOS | 15.1 |
203
192
  | Node | 20 |
204
193
 
205
- Both architectures supported; RN 0.82 removed Legacy Architecture, so that half only matters on 0.81 and below.
194
+ Both architectures are supported. RN 0.82 removed the Legacy Architecture, so it only matters on 0.81 and below.
206
195
 
207
196
  ### Platform support per provider
208
197
 
@@ -214,7 +203,7 @@ Both architectures supported; RN 0.82 removed Legacy Architecture, so that half
214
203
  | `icloudDocuments` | native | - | - |
215
204
  | `googleDrive` | REST | REST | REST |
216
205
 
217
- 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.
206
+ An unavailable provider rejects with `ERR_UNSUPPORTED_PLATFORM`; it never silently does nothing. Trade-offs: [Choosing a provider](https://kesha-antonov.com/react-native-cloud-sync/choosing-a-provider).
218
207
 
219
208
  ## ๐Ÿ“ฆ Installation
220
209
 
@@ -236,13 +225,13 @@ Add the config plugin, then rebuild:
236
225
  }
237
226
  ```
238
227
 
239
- Bare React Native and manual `ios/` entitlement keys: see [Installation](https://kesha-antonov.github.io/react-native-cloud-sync/installation).
228
+ Bare React Native and manual `ios/` entitlements: see [Installation](https://kesha-antonov.com/react-native-cloud-sync/installation).
240
229
 
241
230
  ## ๐Ÿš€ Quick start
242
231
 
243
232
  ### iCloud key-value store
244
233
 
245
- No sign-in and no UI; it uses the device's existing account.
234
+ No sign-in, no UI: it uses the device's iCloud account.
246
235
 
247
236
  ```ts
248
237
  import { icloudKV } from 'react-native-cloud-sync'
@@ -254,11 +243,11 @@ const theme = await icloudKV.getItem('settings/theme')
254
243
  icloudKV.onRemoteChange(({ keys }) => reload(keys))
255
244
  ```
256
245
 
257
- [Full guide](https://kesha-antonov.github.io/react-native-cloud-sync/providers/icloud-kv)
246
+ [Full guide](https://kesha-antonov.com/react-native-cloud-sync/providers/icloud-kv)
258
247
 
259
248
  ### CloudKit
260
249
 
261
- The same private database from iOS, Android and web.
250
+ One private database on iOS, Android and web.
262
251
 
263
252
  ```ts
264
253
  import { cloudKit, cloudKitAssets } from 'react-native-cloud-sync'
@@ -270,11 +259,11 @@ const raw = await cloudKit.getItem('playlist')
270
259
  await cloudKitAssets.save({ recordName: 'avatar', fieldName: 'image', fileUri })
271
260
  ```
272
261
 
273
- 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)
262
+ Android and web need an Apple ID sign-in whose token lasts up to two weeks: fine for an explicit import, not for background sync. [Full guide](https://kesha-antonov.com/react-native-cloud-sync/providers/cloudkit)
274
263
 
275
264
  ### Sensitive data
276
265
 
277
- CloudKit's own end-to-end encryption: Apple stores ciphertext and holds no key.
266
+ CloudKit end-to-end encryption: Apple stores ciphertext and holds no key.
278
267
 
279
268
  ```ts
280
269
  import { cloudKitEncrypted } from 'react-native-cloud-sync'
@@ -282,7 +271,7 @@ import { cloudKitEncrypted } from 'react-native-cloud-sync'
282
271
  await cloudKitEncrypted.setItem('auth.refreshToken', token)
283
272
  ```
284
273
 
285
- 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)
274
+ Apple only: the key lives in the user's iCloud Keychain. For cross-platform encryption use the store's `codec`. [Full guide](https://kesha-antonov.com/react-native-cloud-sync/encryption)
286
275
 
287
276
  ### iCloud Drive
288
277
 
@@ -297,11 +286,11 @@ await icloudDocuments.save({ fileUri: localPath, name: 'Export 2024.csv' })
297
286
  const path = await icloudDocuments.fetch({ name: 'Export 2024.csv' })
298
287
  ```
299
288
 
300
- [Full guide](https://kesha-antonov.github.io/react-native-cloud-sync/providers/icloud-drive)
289
+ [Full guide](https://kesha-antonov.com/react-native-cloud-sync/providers/icloud-drive)
301
290
 
302
291
  ### Google Drive
303
292
 
304
- Identical behaviour on every platform, no periodic re-auth.
293
+ Same behaviour on every platform, no periodic re-auth.
305
294
 
306
295
  ```ts
307
296
  import { configureGoogleDrive, googleDrive } from 'react-native-cloud-sync'
@@ -313,7 +302,7 @@ configureGoogleDrive({
313
302
  await googleDrive.setItem('playlist.json', JSON.stringify(tracks))
314
303
  ```
315
304
 
316
- [Full guide](https://kesha-antonov.github.io/react-native-cloud-sync/providers/google-drive)
305
+ [Full guide](https://kesha-antonov.com/react-native-cloud-sync/providers/google-drive)
317
306
 
318
307
  ### All of them at once
319
308
 
@@ -322,7 +311,7 @@ import { createCloudStore } from 'react-native-cloud-sync'
322
311
 
323
312
  const store = createCloudStore({
324
313
  providers: ['icloudKV', 'googleDrive'], // preference order
325
- writeMode: 'mirror', // write to both providers, not only the preferred one
314
+ writeMode: 'mirror', // write to every provider, not only the first
326
315
  resolve: resolveByTimestamp('updatedAt'), // read whichever copy is newest
327
316
  tiering: 'auto', // route by size
328
317
  outboxStorage: mmkvAdapter, // survive restarts
@@ -332,7 +321,7 @@ await store.setItem('playlist', json)
332
321
  await store.flushOutbox() // on reconnect
333
322
  ```
334
323
 
335
- 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)
324
+ `mirror` copies writes to Drive so non-Apple devices can read them. `resolve` keeps an Apple device from serving a stale iCloud copy. Together they sync **both** ways across a mixed fleet. [Full guide](https://kesha-antonov.com/react-native-cloud-sync/store)
336
325
 
337
326
  ### In a component
338
327
 
@@ -342,7 +331,7 @@ import { useCloudItem } from 'react-native-cloud-sync/hooks'
342
331
  const { value, setValue, loading, error } = useCloudItem<Settings>(store, 'settings')
343
332
  ```
344
333
 
345
- 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)
334
+ Re-reads on remote writes, drops stale responses, no `setState` after unmount. [Full guide](https://kesha-antonov.com/react-native-cloud-sync/hooks)
346
335
 
347
336
  ### Handling failures
348
337
 
@@ -357,7 +346,7 @@ try {
357
346
  }
358
347
  ```
359
348
 
360
- [Full guide](https://kesha-antonov.github.io/react-native-cloud-sync/errors)
349
+ [Full guide](https://kesha-antonov.com/react-native-cloud-sync/errors)
361
350
 
362
351
  ## ๐Ÿงช Testing
363
352
 
@@ -372,11 +361,11 @@ const provider = createMemoryProvider({
372
361
  provider.emitAccountChange({ status: 'available', identityChanged: true })
373
362
  ```
374
363
 
375
- 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)
364
+ Test signed-out, offline and account-switch paths in Jest, no device needed. [Full guide](https://kesha-antonov.com/react-native-cloud-sync/testing)
376
365
 
377
366
  ## ๐Ÿงช Example App
378
367
 
379
- A playground covering every API, plus a live sync demo for side-by-side recording:
368
+ A playground for every API, plus a live sync demo for side-by-side recording:
380
369
 
381
370
  ```sh
382
371
  cd example
@@ -392,13 +381,13 @@ Tabs: **Sync** (shared counter, one-tap mirror mode to iCloud+Drive), **iCloud K
392
381
 
393
382
  ## ๐Ÿค Contributing
394
383
 
395
- Issues and pull requests welcome. Run `yarn lint`, `yarn typecheck` and `yarn test` before opening one.
384
+ Issues and pull requests welcome. Run `yarn lint`, `yarn typecheck` and `yarn test` first.
396
385
 
397
386
  ## ๐Ÿ‘ฅ Authors
398
387
 
399
388
  - [Kesha Antonov](https://github.com/kesha-antonov)
400
389
 
401
- 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.
390
+ This library was built for **[cryptoc](https://cryptoc-app.web.app/)**, my crypto portfolio app.
402
391
 
403
392
  ## ๐Ÿ“„ License
404
393
 
@@ -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,