react-native-cloud-sync 0.2.0 → 0.4.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 (55) hide show
  1. package/README.md +120 -80
  2. package/lib/commonjs/config.js +11 -1
  3. package/lib/commonjs/config.js.map +1 -1
  4. package/lib/commonjs/hooks.js +242 -0
  5. package/lib/commonjs/hooks.js.map +1 -1
  6. package/lib/commonjs/index.js.map +1 -1
  7. package/lib/commonjs/internal/cloudKitRest.js +205 -21
  8. package/lib/commonjs/internal/cloudKitRest.js.map +1 -1
  9. package/lib/commonjs/internal/googleDriveRest.js +173 -38
  10. package/lib/commonjs/internal/googleDriveRest.js.map +1 -1
  11. package/lib/commonjs/providers/cloudKit.js +89 -19
  12. package/lib/commonjs/providers/cloudKit.js.map +1 -1
  13. package/lib/module/config.js +10 -1
  14. package/lib/module/config.js.map +1 -1
  15. package/lib/module/hooks.js +240 -0
  16. package/lib/module/hooks.js.map +1 -1
  17. package/lib/module/index.js +2 -2
  18. package/lib/module/index.js.map +1 -1
  19. package/lib/module/internal/cloudKitRest.js +205 -21
  20. package/lib/module/internal/cloudKitRest.js.map +1 -1
  21. package/lib/module/internal/googleDriveRest.js +174 -39
  22. package/lib/module/internal/googleDriveRest.js.map +1 -1
  23. package/lib/module/providers/cloudKit.js +92 -22
  24. package/lib/module/providers/cloudKit.js.map +1 -1
  25. package/lib/typescript/commonjs/config.d.ts +8 -0
  26. package/lib/typescript/commonjs/config.d.ts.map +1 -1
  27. package/lib/typescript/commonjs/hooks.d.ts +68 -0
  28. package/lib/typescript/commonjs/hooks.d.ts.map +1 -1
  29. package/lib/typescript/commonjs/index.d.ts +3 -3
  30. package/lib/typescript/commonjs/index.d.ts.map +1 -1
  31. package/lib/typescript/commonjs/internal/cloudKitRest.d.ts +90 -0
  32. package/lib/typescript/commonjs/internal/cloudKitRest.d.ts.map +1 -1
  33. package/lib/typescript/commonjs/internal/googleDriveRest.d.ts +73 -8
  34. package/lib/typescript/commonjs/internal/googleDriveRest.d.ts.map +1 -1
  35. package/lib/typescript/commonjs/providers/cloudKit.d.ts +32 -13
  36. package/lib/typescript/commonjs/providers/cloudKit.d.ts.map +1 -1
  37. package/lib/typescript/module/config.d.ts +8 -0
  38. package/lib/typescript/module/config.d.ts.map +1 -1
  39. package/lib/typescript/module/hooks.d.ts +68 -0
  40. package/lib/typescript/module/hooks.d.ts.map +1 -1
  41. package/lib/typescript/module/index.d.ts +3 -3
  42. package/lib/typescript/module/index.d.ts.map +1 -1
  43. package/lib/typescript/module/internal/cloudKitRest.d.ts +90 -0
  44. package/lib/typescript/module/internal/cloudKitRest.d.ts.map +1 -1
  45. package/lib/typescript/module/internal/googleDriveRest.d.ts +73 -8
  46. package/lib/typescript/module/internal/googleDriveRest.d.ts.map +1 -1
  47. package/lib/typescript/module/providers/cloudKit.d.ts +32 -13
  48. package/lib/typescript/module/providers/cloudKit.d.ts.map +1 -1
  49. package/package.json +5 -2
  50. package/src/config.ts +12 -2
  51. package/src/hooks.ts +294 -0
  52. package/src/index.ts +5 -3
  53. package/src/internal/cloudKitRest.ts +272 -29
  54. package/src/internal/googleDriveRest.ts +196 -42
  55. package/src/providers/cloudKit.ts +138 -41
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 - on iOS, Android and the web, on both React Native 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,46 +23,84 @@
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
+ <sub>Using it in production? A ⭐ helps other developers find the library.</sub>
28
+ </p>
29
+
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
48
+
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.
50
+
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
56
+
57
+ <sub>This is the app the library was built for. Downloading it pays for the time that goes into maintaining it.</sub>
58
+
59
+ </td>
60
+ </tr>
61
+ </table>
62
+
63
+ <hr />
27
64
 
28
65
  ## ✨ Features
29
66
 
30
- - ☁️ **Four providers, one API** - [`NSUbiquitousKeyValueStore`][kvs] (iCloud's key-value store), [CloudKit][ck] records, [iCloud Drive][icdrive] documents and Google Drive [`appDataFolder`][appdata], each usable directly or through a single facade.
31
- - 🍏 **CloudKit from Android and the web** - the same [private database][ckdb] your iOS app writes to, over [CloudKit Web Services][ckws]. No other React Native library offers this.
32
- - 📂 **Files the user can actually see** - `icloudDocuments` writes into their iCloud Drive, visible in Files.app. A `CKAsset` is invisible to the user; this is the one thing no CloudKit API can do.
33
- - 🚨 **Errors you can act on** - every failure is a typed rejection (`ERR_NOT_SIGNED_IN`, `ERR_QUOTA_EXCEEDED`, `ERR_RATE_LIMITED` with `retryAfterMs`, ...). `null` means one thing only: the key does not exist - never "we could not reach the cloud".
34
- - 👤 **Real account lifecycle** - all five [`CKAccountStatus`][ckstatus] values, plus `onAccountChange` with an `identityChanged` flag. The store acts on it too: provider caches and queued writes belonging to the previous user are dropped, not leaked into the next account.
35
- - 🔔 **Remote change events** - `onRemoteChange` on every provider *and* on the facade, including Google Drive via its change cursor.
36
- - 📦 **Automatic size tiering** - small values to the key-value store, larger to a [`CKRecord`][ckrecord] field. Binary goes in as a [`CKAsset`][ckasset] or a resumable Drive upload. Store limits stop leaking into your product code.
37
- - 🔁 **Durable outbox** - retryable failures are queued and retried with backoff that honours server retry hints, drained automatically on foreground, bounded so it cannot grow forever, and never allowed to overwrite a newer write.
38
- - 🧺 **Batch operations** - `multiGet`/`multiSet`/`multiRemove`/`clear`, one request per provider that genuinely batches rather than a loop wearing a batch's clothes.
39
- - 🪝 **React hooks** - `useCloudItem`, `useAccountStatus`, `usePendingWrites`, from `/hooks`, without the stale-response and unmounted-`setState` bugs every hand-rolled version has.
40
- - 🔐 **Real end-to-end encryption** - `cloudKitEncrypted` uses CloudKit's own `encryptedValues`, so Apple stores ciphertext and holds no key, with nothing for you to manage. Everywhere else, a `codec` seam for a cipher you chose - because Drive's `appDataFolder` is plaintext to anything holding the OAuth token.
41
- - 🧪 **A real testing story** - an in-memory provider with fault injection plus the native mock itself, both exported from the package (`/testing`, `/jest-mock`), so signed-out, offline, quota-exceeded and account-switch paths are all testable in Jest.
42
- - ⚙️ **Old and new architecture** - React Native 0.71 through 0.86+, with the `#ifdef` bridge to prove it.
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.
43
81
 
44
82
  ## 💡 Why?
45
83
 
46
- Cloud storage in React Native is fragmented into single-provider wrappers, and almost all of them repeat the same handful of defects. Two independent libraries in this space ship a `setItem` that **reports a failed write as a success** - one checks the wrong error variable in its completion block, the other discards the operation result entirely. A third flattens five distinct iCloud account states into one boolean. A fourth has an open issue titled *"Idea: Listening for changes"* whose author replied *"Good idea, let's do it!"*, opened the PR himself, and left it unmerged for six months.
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.
47
85
 
48
- The common thread is that failure paths are treated as an afterthought. A `catch { return null }` makes "not signed in", "offline", "out of storage" and "no such key" indistinguishable - so apps cannot tell the user anything useful, and cannot decide whether to retry.
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.
49
87
 
50
- This library starts from the opposite end: the error contract first, then the providers.
88
+ This library was built error contract first, providers second.
51
89
 
52
90
  ## 📚 Upstream documentation
53
91
 
54
- This package is a wrapper. When something behaves unexpectedly, the answer is usually in Apple's or Google's documentation rather than ours - so here is where to look.
92
+ This package is a wrapper. When something behaves unexpectedly, the answer is usually in Apple's or Google's docs.
55
93
 
56
94
  **Apple**
57
95
 
58
96
  | | |
59
97
  |---|---|
60
- | [`NSUbiquitousKeyValueStore`][kvs] | The iCloud key-value store, and its 1 MB / 1024-key limits |
98
+ | [`NSUbiquitousKeyValueStore`][kvs] | The iCloud key-value store; 1 MB / 1024-key limits |
61
99
  | [CloudKit][ck] · [`CKDatabase`][ckdb] · [`CKRecord`][ckrecord] | Records in the user's private database |
62
100
  | [`CKAsset`][ckasset] · [`CKRecordZone`][ckzone] | Binary assets and custom zones |
63
101
  | [`CKAccountStatus`][ckstatus] | The five account states this package surfaces verbatim |
64
102
  | [CloudKit Web Services][ckws] | The REST API behind the Android and web paths |
65
- | [Authentication][ckauth] · [Data size limits][cklimits] · [Error codes][ckerrors] | The three pages worth reading before shipping CloudKit on Android |
103
+ | [Authentication][ckauth] · [Data size limits][cklimits] · [Error codes][ckerrors] | Worth reading before shipping CloudKit on Android |
66
104
  | [iCloud entitlements][entitlements] | The keys the config plugin writes |
67
105
  | [CloudKit Console][console] | Where containers, schemas, API tokens and the sign-in callback live |
68
106
 
@@ -72,7 +110,7 @@ This package is a wrapper. When something behaves unexpectedly, the answer is us
72
110
  |---|---|
73
111
  | [The `appDataFolder`][appdata] | The hidden per-app folder this package stores into |
74
112
  | [Drive `files` resource][drivefiles] | The REST endpoints behind the provider |
75
- | [Drive API scopes][drivescopes] | Why `drive.appdata` and not something broader |
113
+ | [Drive API scopes][drivescopes] | Why the scope is `drive.appdata` |
76
114
 
77
115
  [kvs]: https://developer.apple.com/documentation/foundation/nsubiquitouskeyvaluestore
78
116
  [ck]: https://developer.apple.com/documentation/cloudkit
@@ -96,40 +134,40 @@ This package is a wrapper. When something behaves unexpectedly, the answer is us
96
134
 
97
135
  | | **this** | [kuatsu/<br />cloud-storage][kuatsu] | [icloud-kit][ik] | [expo-cloudkit][ec] | [okwasniewski/<br />icloud-storage][ok] | [cloudkit-<br />storage][jp] |
98
136
  |---|:---:|:---:|:---:|:---:|:---:|:---:|
99
- | iCloud key-value store | ✅ | ✅ | ✅ | – | ✅ | – |
100
- | CloudKit records | ✅ | – | ✅ | ✅ | – | ✅ |
101
- | Google Drive | ✅ | ✅ | – | – | – | – |
137
+ | iCloud key-value store | ✅ | ✅ | ✅ | - | ✅ | - |
138
+ | CloudKit records | ✅ | - | ✅ | ✅ | - | ✅ |
139
+ | Google Drive | ✅ | ✅ | - | - | - | - |
102
140
  | iOS | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
103
- | Android | ✅ | ✅ | – | ❌ [^1] | – | – |
104
- | Web | ✅ | partial [^2] | – | – | – | – |
105
- | **CloudKit on Android/web** | ✅ | – | – | ❌ [^1] | – | – |
106
- | New Architecture | ✅ | ✅ | ✅ | ✅ | ✅ | – |
107
- | **Legacy Architecture** | ✅ | ❌ | ✅ [^3] | ✅ [^3] | ✅ [^3] | ✅ |
108
- | Typed error codes | ✅ | – | partial | ✅ | – | – |
109
- | 5-value account status | ✅ | boolean | boolean | ✅ | – | – |
110
- | Identity-change event | ✅ | ⚠️ [^4] | – | ✅ | – | – |
111
- | Remote-change event | ✅ | ✅ | – | n/a | ❌ [^5] | ✅ |
112
- | Offline write queue | ✅ | – | – | ✅ | – | – |
113
- | Size tiering | ✅ | – | – | – | – | – |
114
- | Binary / assets | ✅ [^9] | ✅ | ❌ [^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] | – | – |
121
- | Mac Catalyst | ✅ | – | – | ⚠️ | – | – |
122
- | Actively maintained | ✅ | ✅ | ✅ | ❌ [^8] | ❌ [^5] | ❌ |
123
-
124
- [^1]: expo-cloudkit's README states Android returns `CloudKitNotSupportedError` on every call.
125
- [^2]: Text-based Google Drive operations only.
126
- [^3]: Expo Modules API supports both architectures, but these packages require `expo-modules-core`.
127
- [^4]: The event exists and has crashed with `std::bad_function_call` (SIGABRT) when it fires before JS binds the emitter - reported independently three times.
128
- [^5]: One version ever published; the change-listener PR has been open since February.
129
- [^6]: Its field type is `string | number | null`, so binary data cannot be stored at all.
130
- [^7]: A mock factory exists but is not exported from the package entry and is not mentioned in the README.
131
- [^8]: No commits since April; four npm releases shipped with Swift that did not compile.
132
- [^9]: `CKAsset`, streamed from disk, on Apple platforms. Not yet implemented over CloudKit Web Services, so on Android and web asset calls reject with `ERR_UNSUPPORTED_PLATFORM` rather than appearing to work - use [`googleDriveFiles`](https://kesha-antonov.github.io/react-native-cloud-sync/providers/google-drive#large-files) for binaries there, which chunks and resumes the same way `CKAsset` does.
141
+ | Android | ✅ | ✅ | - | ❌ [[1]](#note-1) | - | - |
142
+ | Web | ✅ | partial [[2]](#note-2) | - | - | - | - |
143
+ | **CloudKit on Android/web** | ✅ | - | - | ❌ [[1]](#note-1) | - | - |
144
+ | New Architecture | ✅ | ✅ | ✅ | ✅ | ✅ | - |
145
+ | **Legacy Architecture** | ✅ | ❌ | ✅ [[3]](#note-3) | ✅ [[3]](#note-3) | ✅ [[3]](#note-3) | ✅ |
146
+ | Typed error codes | ✅ | - | partial | ✅ | - | - |
147
+ | 5-value account status | ✅ | boolean | boolean | ✅ | - | - |
148
+ | Identity-change event | ✅ | ⚠️ [[4]](#note-4) | - | ✅ | - | - |
149
+ | Remote-change event | ✅ | ✅ | - | n/a | ❌ [[5]](#note-5) | ✅ |
150
+ | Offline write queue | ✅ | - | - | ✅ | - | - |
151
+ | Size tiering | ✅ | - | - | - | - | - |
152
+ | Binary / assets | ✅ [[9]](#note-9) | ✅ | ❌ [[6]](#note-6) | ✅ | - | - |
153
+ | User-visible iCloud Drive files | ✅ | - | - | - | ✅ | - |
154
+ | Native end-to-end encryption | ✅ | - | - | - | - | - |
155
+ | Batch operations | ✅ | - | - | - | - | - |
156
+ | React hooks | ✅ | ✅ | - | - | - | - |
157
+ | Encryption seam | ✅ | - | - | - | - | - |
158
+ | Exported test harness | ✅ | - | - | ⚠️ [[7]](#note-7) | - | - |
159
+ | Mac Catalyst | ✅ | - | - | ⚠️ | - | - |
160
+ | Actively maintained | ✅ | ✅ | ✅ | ❌ [[8]](#note-8) | ❌ [[5]](#note-5) | ❌ |
161
+
162
+ <a id="note-1"></a>**[1]** expo-cloudkit's README: Android throws `CloudKitNotSupportedError` on every call.
163
+ <a id="note-2"></a>**[2]** Google Drive support is text-based only.
164
+ <a id="note-3"></a>**[3]** Via the Expo Modules API; pulls in `expo-modules-core`.
165
+ <a id="note-4"></a>**[4]** Fires before JS binds the emitter, crashing with `std::bad_function_call` (SIGABRT); hit three times.
166
+ <a id="note-5"></a>**[5]** One version ever shipped; the change-listener PR has sat open since February.
167
+ <a id="note-6"></a>**[6]** Field type is `string | number | null`, so it can't hold binary data.
168
+ <a id="note-7"></a>**[7]** A mock factory exists, but isn't exported or documented.
169
+ <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.
133
171
 
134
172
  [kuatsu]: https://github.com/kuatsu/react-native-cloud-storage
135
173
  [ik]: https://github.com/BogdanGeorgian91/react-native-icloud-kit
@@ -141,14 +179,14 @@ This package is a wrapper. When something behaves unexpectedly, the answer is us
141
179
 
142
180
  | | |
143
181
  |---|---|
144
- | [Choosing a provider](https://kesha-antonov.github.io/react-native-cloud-sync/choosing-a-provider) | Which one, what each costs you, and why to let the user pick |
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 |
145
183
  | [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 |
184
+ | [CloudKit](https://kesha-antonov.github.io/react-native-cloud-sync/providers/cloudkit) | Records, zones, assets, and the Android/web path |
147
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 |
148
186
  | [Google Drive](https://kesha-antonov.github.io/react-native-cloud-sync/providers/google-drive) | The always-on cross-platform backend |
149
187
  | [The store facade](https://kesha-antonov.github.io/react-native-cloud-sync/store) | Tiering, outbox, migration, fallthrough |
150
188
  | [Error handling](https://kesha-antonov.github.io/react-native-cloud-sync/errors) | The typed contract |
151
- | [Encryption](https://kesha-antonov.github.io/react-native-cloud-sync/encryption) | What is encrypted for you, and how to add end-to-end yourself |
189
+ | [Encryption](https://kesha-antonov.github.io/react-native-cloud-sync/encryption) | What's encrypted for you, and how to add your own |
152
190
  | [React hooks](https://kesha-antonov.github.io/react-native-cloud-sync/hooks) | Binding cloud state to components |
153
191
  | [Recipes](https://kesha-antonov.github.io/react-native-cloud-sync/recipes) | Backup/restore, migration, offline-first |
154
192
  | [Testing](https://kesha-antonov.github.io/react-native-cloud-sync/testing) | Fault injection without a device |
@@ -164,19 +202,19 @@ This package is a wrapper. When something behaves unexpectedly, the answer is us
164
202
  | iOS | 15.1 |
165
203
  | Node | 20 |
166
204
 
167
- Both architectures are supported. React Native 0.82 removed the Legacy Architecture, so that half matters only on 0.81 and below.
205
+ Both architectures supported; RN 0.82 removed Legacy Architecture, so that half only matters on 0.81 and below.
168
206
 
169
207
  ### Platform support per provider
170
208
 
171
209
  | | iOS / macOS | Android | Web |
172
210
  |---|:---:|:---:|:---:|
173
- | `icloudKV` | native | – | – |
211
+ | `icloudKV` | native | - | - |
174
212
  | `cloudKit` | native | REST | REST |
175
- | `cloudKitEncrypted` | native | – | – |
176
- | `icloudDocuments` | native | – | – |
213
+ | `cloudKitEncrypted` | native | - | - |
214
+ | `icloudDocuments` | native | - | - |
177
215
  | `googleDrive` | REST | REST | REST |
178
216
 
179
- Where a provider is unavailable it rejects with `ERR_UNSUPPORTED_PLATFORM` rather than silently doing nothing. [Choosing a provider](https://kesha-antonov.github.io/react-native-cloud-sync/choosing-a-provider) covers the trade-offs.
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.
180
218
 
181
219
  ## 📦 Installation
182
220
 
@@ -198,13 +236,13 @@ Add the config plugin, then rebuild:
198
236
  }
199
237
  ```
200
238
 
201
- Bare React Native, and the raw entitlement keys if you manage `ios/` yourself: see [Installation](https://kesha-antonov.github.io/react-native-cloud-sync/installation).
239
+ Bare React Native and manual `ios/` entitlement keys: see [Installation](https://kesha-antonov.github.io/react-native-cloud-sync/installation).
202
240
 
203
241
  ## 🚀 Quick start
204
242
 
205
243
  ### iCloud key-value store
206
244
 
207
- No sign-in, no UI - it uses the account already on the device.
245
+ No sign-in and no UI; it uses the device's existing account.
208
246
 
209
247
  ```ts
210
248
  import { icloudKV } from 'react-native-cloud-sync'
@@ -216,7 +254,7 @@ const theme = await icloudKV.getItem('settings/theme')
216
254
  icloudKV.onRemoteChange(({ keys }) => reload(keys))
217
255
  ```
218
256
 
219
- [Full guide →](https://kesha-antonov.github.io/react-native-cloud-sync/providers/icloud-kv)
257
+ [Full guide](https://kesha-antonov.github.io/react-native-cloud-sync/providers/icloud-kv)
220
258
 
221
259
  ### CloudKit
222
260
 
@@ -232,11 +270,11 @@ const raw = await cloudKit.getItem('playlist')
232
270
  await cloudKitAssets.save({ recordName: 'avatar', fieldName: 'image', fileUri })
233
271
  ```
234
272
 
235
- On Android and web this needs an Apple ID sign-in whose token lasts at most two weeks, so treat it as an explicit import rather than background sync. [Full guide →](https://kesha-antonov.github.io/react-native-cloud-sync/providers/cloudkit)
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)
236
274
 
237
275
  ### Sensitive data
238
276
 
239
- CloudKit's own end-to-end encryption - Apple stores ciphertext and holds no key.
277
+ CloudKit's own end-to-end encryption: Apple stores ciphertext and holds no key.
240
278
 
241
279
  ```ts
242
280
  import { cloudKitEncrypted } from 'react-native-cloud-sync'
@@ -244,11 +282,11 @@ import { cloudKitEncrypted } from 'react-native-cloud-sync'
244
282
  await cloudKitEncrypted.setItem('auth.refreshToken', token)
245
283
  ```
246
284
 
247
- Apple-only by construction: the key lives in the user's iCloud Keychain, so nothing server-side can decrypt it. For cross-platform encryption, the store takes a `codec`. [Full guide →](https://kesha-antonov.github.io/react-native-cloud-sync/encryption)
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)
248
286
 
249
287
  ### iCloud Drive
250
288
 
251
- Files the user can open in Files.app - not hidden in a private database.
289
+ Files the user can open in Files.app.
252
290
 
253
291
  ```ts
254
292
  import { icloudDocuments } from 'react-native-cloud-sync'
@@ -259,7 +297,7 @@ await icloudDocuments.save({ fileUri: localPath, name: 'Export 2024.csv' })
259
297
  const path = await icloudDocuments.fetch({ name: 'Export 2024.csv' })
260
298
  ```
261
299
 
262
- [Full guide →](https://kesha-antonov.github.io/react-native-cloud-sync/providers/icloud-drive)
300
+ [Full guide](https://kesha-antonov.github.io/react-native-cloud-sync/providers/icloud-drive)
263
301
 
264
302
  ### Google Drive
265
303
 
@@ -275,7 +313,7 @@ configureGoogleDrive({
275
313
  await googleDrive.setItem('playlist.json', JSON.stringify(tracks))
276
314
  ```
277
315
 
278
- [Full guide →](https://kesha-antonov.github.io/react-native-cloud-sync/providers/google-drive)
316
+ [Full guide](https://kesha-antonov.github.io/react-native-cloud-sync/providers/google-drive)
279
317
 
280
318
  ### All of them at once
281
319
 
@@ -284,8 +322,8 @@ import { createCloudStore } from 'react-native-cloud-sync'
284
322
 
285
323
  const store = createCloudStore({
286
324
  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
325
+ writeMode: 'mirror', // write to both providers, not only the preferred one
326
+ resolve: resolveByTimestamp('updatedAt'), // read whichever copy is newest
289
327
  tiering: 'auto', // route by size
290
328
  outboxStorage: mmkvAdapter, // survive restarts
291
329
  })
@@ -294,7 +332,7 @@ await store.setItem('playlist', json)
294
332
  await store.flushOutbox() // on reconnect
295
333
  ```
296
334
 
297
- Those two options are what make sync work in **both** directions across a mixed fleet - an Android phone and an iPad, a browser and a Mac. `mirror` puts a copy in Drive so a non-Apple device has something to read; `resolve` stops an Apple device serving its own stale iCloud copy without ever consulting Drive. Either platform can be the one the user started on. [Full guide →](https://kesha-antonov.github.io/react-native-cloud-sync/store)
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)
298
336
 
299
337
  ### In a component
300
338
 
@@ -304,7 +342,7 @@ import { useCloudItem } from 'react-native-cloud-sync/hooks'
304
342
  const { value, setValue, loading, error } = useCloudItem<Settings>(store, 'settings')
305
343
  ```
306
344
 
307
- Re-reads when another device writes, drops stale responses, and never calls `setState` after unmount. [Full guide →](https://kesha-antonov.github.io/react-native-cloud-sync/hooks)
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)
308
346
 
309
347
  ### Handling failures
310
348
 
@@ -319,7 +357,7 @@ try {
319
357
  }
320
358
  ```
321
359
 
322
- [Full guide →](https://kesha-antonov.github.io/react-native-cloud-sync/errors)
360
+ [Full guide](https://kesha-antonov.github.io/react-native-cloud-sync/errors)
323
361
 
324
362
  ## 🧪 Testing
325
363
 
@@ -334,11 +372,11 @@ const provider = createMemoryProvider({
334
372
  provider.emitAccountChange({ status: 'available', identityChanged: true })
335
373
  ```
336
374
 
337
- Signed-out, offline, quota-exceeded, rate-limited and account-switch paths, all in Jest without a device. [Full guide →](https://kesha-antonov.github.io/react-native-cloud-sync/testing)
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)
338
376
 
339
377
  ## 🧪 Example App
340
378
 
341
- A playground covering every API, plus a live sync demo built for side-by-side recording:
379
+ A playground covering every API, plus a live sync demo for side-by-side recording:
342
380
 
343
381
  ```sh
344
382
  cd example
@@ -346,7 +384,7 @@ yarn installDevBuild:ios # or :android
346
384
  yarn start:web
347
385
  ```
348
386
 
349
- Tabs: **Sync** (shared counter across devices, including a one-tap mirror mode that writes to iCloud and Drive at once), **iCloud KV**, **CloudKit**, **Drive**, **Files** (large-file backup/restore, including a working `GoogleDriveFileAdapter`), **Store** and **Faults**.
387
+ Tabs: **Sync** (shared counter, one-tap mirror mode to iCloud+Drive), **iCloud KV**, **CloudKit**, **Drive**, **Files** (large-file backup/restore via `GoogleDriveFileAdapter`), **Store**, **Faults**.
350
388
 
351
389
  <p align="center">
352
390
  <img src="assets/screenshots/sync.png" width="18%" alt="Sync demo tab - shared counter with mirror provider selection" />&nbsp;&nbsp;<img src="assets/screenshots/icloud-kv.png" width="18%" alt="iCloud key-value store tab" />&nbsp;&nbsp;<img src="assets/screenshots/cloudkit.png" width="18%" alt="CloudKit tab - record read/write and oversized-write handling" />&nbsp;&nbsp;<img src="assets/screenshots/drive.png" width="18%" alt="Google Drive tab - OAuth token configuration and file operations" />&nbsp;&nbsp;<img src="assets/screenshots/store.png" width="18%" alt="Store facade tab - size tiering across providers" />
@@ -360,6 +398,8 @@ Issues and pull requests welcome. Run `yarn lint`, `yarn typecheck` and `yarn te
360
398
 
361
399
  - [Kesha Antonov](https://github.com/kesha-antonov)
362
400
 
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.
402
+
363
403
  ## 📄 License
364
404
 
365
405
  MIT
@@ -10,6 +10,7 @@ exports.configureGoogleDriveFiles = configureGoogleDriveFiles;
10
10
  exports.getCloudKitClient = getCloudKitClient;
11
11
  exports.getGoogleDriveClient = getGoogleDriveClient;
12
12
  exports.getGoogleDriveFileAdapter = getGoogleDriveFileAdapter;
13
+ exports.getSharedFileAdapter = void 0;
13
14
  exports.isCloudKitConfigured = isCloudKitConfigured;
14
15
  exports.isGoogleDriveConfigured = isGoogleDriveConfigured;
15
16
  exports.isGoogleDriveFilesConfigured = isGoogleDriveFilesConfigured;
@@ -67,11 +68,20 @@ function configureGoogleDriveFiles(adapter) {
67
68
  driveFileAdapter = adapter;
68
69
  }
69
70
  function getGoogleDriveFileAdapter() {
70
- if (driveFileAdapter == null) throw new _errors.CloudSyncError(_errors.ErrorCode.CONTAINER_MISCONFIGURED, '[RNCloudSync] googleDriveFiles needs a file adapter. Call configureGoogleDriveFiles({ ' + 'statSize, readChunk, writeChunk, appendChunk }) before saving or fetching a file.', {
71
+ if (driveFileAdapter == null) throw new _errors.CloudSyncError(_errors.ErrorCode.CONTAINER_MISCONFIGURED, '[RNCloudSync] This needs a file adapter. Call configureGoogleDriveFiles({ ' + 'statSize, readChunk, writeChunk, appendChunk }) before saving or fetching a file - shared ' + 'by googleDriveFiles and by cloudKitAssets on Android/web.', {
71
72
  provider: 'googleDrive'
72
73
  });
73
74
  return driveFileAdapter;
74
75
  }
76
+
77
+ /**
78
+ * Same adapter and same `configureGoogleDriveFiles` call, under a name that
79
+ * doesn't imply it's Drive-specific. `cloudKitAssets`'s REST path (Android/web)
80
+ * reads and writes local files the exact same way `googleDriveFiles` does, and
81
+ * asking a host app to register two near-identical adapters for that would be
82
+ * pure friction for no benefit.
83
+ */
84
+ const getSharedFileAdapter = exports.getSharedFileAdapter = getGoogleDriveFileAdapter;
75
85
  function isGoogleDriveFilesConfigured() {
76
86
  return driveFileAdapter != null;
77
87
  }
@@ -1 +1 @@
1
- {"version":3,"names":["_cloudKitRest","require","_googleDriveRest","_errors","cloudKitClient","driveClient","driveFileAdapter","configureCloudKit","config","CloudKitRestClient","getCloudKitClient","CloudSyncError","ErrorCode","CONTAINER_MISCONFIGURED","provider","isCloudKitConfigured","configureGoogleDrive","GoogleDriveClient","getGoogleDriveClient","isGoogleDriveConfigured","configureGoogleDriveFiles","adapter","getGoogleDriveFileAdapter","isGoogleDriveFilesConfigured","__resetConfig"],"sourceRoot":"../../src","sources":["config.ts"],"mappings":";;;;;;;;;;;;;;;AACA,IAAAA,aAAA,GAAAC,OAAA;AAEA,IAAAC,gBAAA,GAAAD,OAAA;AACA,IAAAE,OAAA,GAAAF,OAAA;AAEA,IAAIG,cAAyC,GAAG,IAAI;AACpD,IAAIC,WAAqC,GAAG,IAAI;AAChD,IAAIC,gBAA+C,GAAG,IAAI;;AAE1D;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,iBAAiBA,CAACC,MAA0B,EAAQ;EAClEJ,cAAc,GAAG,IAAIK,gCAAkB,CAACD,MAAM,CAAC;AACjD;AAEO,SAASE,iBAAiBA,CAAA,EAAuB;EACtD,IAAIN,cAAc,IAAI,IAAI,EACxB,MAAM,IAAIO,sBAAc,CACtBC,iBAAS,CAACC,uBAAuB,EACjC,sFAAsF,GACpF,wFAAwF,GACxF,6BAA6B,EAC/B;IAAEC,QAAQ,EAAE;EAAW,CACzB,CAAC;EAEH,OAAOV,cAAc;AACvB;AAEO,SAASW,oBAAoBA,CAAA,EAAY;EAC9C,OAAOX,cAAc,IAAI,IAAI;AAC/B;;AAEA;AACO,SAASY,oBAAoBA,CAACR,MAAyB,EAAQ;EACpEH,WAAW,GAAG,IAAIY,kCAAiB,CAACT,MAAM,CAAC;AAC7C;AAEO,SAASU,oBAAoBA,CAAA,EAAsB;EACxD,IAAIb,WAAW,IAAI,IAAI,EACrB,MAAM,IAAIM,sBAAc,CACtBC,iBAAS,CAACC,uBAAuB,EACjC,4EAA4E,GAC1E,0DAA0D,EAC5D;IAAEC,QAAQ,EAAE;EAAc,CAC5B,CAAC;EAEH,OAAOT,WAAW;AACpB;AAEO,SAASc,uBAAuBA,CAAA,EAAY;EACjD,OAAOd,WAAW,IAAI,IAAI;AAC5B;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASe,yBAAyBA,CAACC,OAA+B,EAAQ;EAC/Ef,gBAAgB,GAAGe,OAAO;AAC5B;AAEO,SAASC,yBAAyBA,CAAA,EAA2B;EAClE,IAAIhB,gBAAgB,IAAI,IAAI,EAC1B,MAAM,IAAIK,sBAAc,CACtBC,iBAAS,CAACC,uBAAuB,EACjC,wFAAwF,GACtF,mFAAmF,EACrF;IAAEC,QAAQ,EAAE;EAAc,CAC5B,CAAC;EAEH,OAAOR,gBAAgB;AACzB;AAEO,SAASiB,4BAA4BA,CAAA,EAAY;EACtD,OAAOjB,gBAAgB,IAAI,IAAI;AACjC;;AAEA;AACO,SAASkB,aAAaA,CAAA,EAAS;EACpCpB,cAAc,GAAG,IAAI;EACrBC,WAAW,GAAG,IAAI;EAClBC,gBAAgB,GAAG,IAAI;AACzB","ignoreList":[]}
1
+ {"version":3,"names":["_cloudKitRest","require","_googleDriveRest","_errors","cloudKitClient","driveClient","driveFileAdapter","configureCloudKit","config","CloudKitRestClient","getCloudKitClient","CloudSyncError","ErrorCode","CONTAINER_MISCONFIGURED","provider","isCloudKitConfigured","configureGoogleDrive","GoogleDriveClient","getGoogleDriveClient","isGoogleDriveConfigured","configureGoogleDriveFiles","adapter","getGoogleDriveFileAdapter","getSharedFileAdapter","exports","isGoogleDriveFilesConfigured","__resetConfig"],"sourceRoot":"../../src","sources":["config.ts"],"mappings":";;;;;;;;;;;;;;;;AACA,IAAAA,aAAA,GAAAC,OAAA;AAEA,IAAAC,gBAAA,GAAAD,OAAA;AACA,IAAAE,OAAA,GAAAF,OAAA;AAEA,IAAIG,cAAyC,GAAG,IAAI;AACpD,IAAIC,WAAqC,GAAG,IAAI;AAChD,IAAIC,gBAA+C,GAAG,IAAI;;AAE1D;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,iBAAiBA,CAACC,MAA0B,EAAQ;EAClEJ,cAAc,GAAG,IAAIK,gCAAkB,CAACD,MAAM,CAAC;AACjD;AAEO,SAASE,iBAAiBA,CAAA,EAAuB;EACtD,IAAIN,cAAc,IAAI,IAAI,EACxB,MAAM,IAAIO,sBAAc,CACtBC,iBAAS,CAACC,uBAAuB,EACjC,sFAAsF,GACpF,wFAAwF,GACxF,6BAA6B,EAC/B;IAAEC,QAAQ,EAAE;EAAW,CACzB,CAAC;EAEH,OAAOV,cAAc;AACvB;AAEO,SAASW,oBAAoBA,CAAA,EAAY;EAC9C,OAAOX,cAAc,IAAI,IAAI;AAC/B;;AAEA;AACO,SAASY,oBAAoBA,CAACR,MAAyB,EAAQ;EACpEH,WAAW,GAAG,IAAIY,kCAAiB,CAACT,MAAM,CAAC;AAC7C;AAEO,SAASU,oBAAoBA,CAAA,EAAsB;EACxD,IAAIb,WAAW,IAAI,IAAI,EACrB,MAAM,IAAIM,sBAAc,CACtBC,iBAAS,CAACC,uBAAuB,EACjC,4EAA4E,GAC1E,0DAA0D,EAC5D;IAAEC,QAAQ,EAAE;EAAc,CAC5B,CAAC;EAEH,OAAOT,WAAW;AACpB;AAEO,SAASc,uBAAuBA,CAAA,EAAY;EACjD,OAAOd,WAAW,IAAI,IAAI;AAC5B;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASe,yBAAyBA,CAACC,OAA+B,EAAQ;EAC/Ef,gBAAgB,GAAGe,OAAO;AAC5B;AAEO,SAASC,yBAAyBA,CAAA,EAA2B;EAClE,IAAIhB,gBAAgB,IAAI,IAAI,EAC1B,MAAM,IAAIK,sBAAc,CACtBC,iBAAS,CAACC,uBAAuB,EACjC,4EAA4E,GAC1E,4FAA4F,GAC5F,2DAA2D,EAC7D;IAAEC,QAAQ,EAAE;EAAc,CAC5B,CAAC;EAEH,OAAOR,gBAAgB;AACzB;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,MAAMiB,oBAAoB,GAAAC,OAAA,CAAAD,oBAAA,GAAGD,yBAAyB;AAEtD,SAASG,4BAA4BA,CAAA,EAAY;EACtD,OAAOnB,gBAAgB,IAAI,IAAI;AACjC;;AAEA;AACO,SAASoB,aAAaA,CAAA,EAAS;EACpCtB,cAAc,GAAG,IAAI;EACrBC,WAAW,GAAG,IAAI;EAClBC,gBAAgB,GAAG,IAAI;AACzB","ignoreList":[]}