react-native-cloud-sync 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (268) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +360 -0
  3. package/app.plugin.js +3 -0
  4. package/ios/CloudSyncError.swift +144 -0
  5. package/ios/CloudSyncImpl.swift +1263 -0
  6. package/ios/RNCloudSync.h +25 -0
  7. package/ios/RNCloudSync.mm +477 -0
  8. package/jest-mock.js +136 -0
  9. package/lib/commonjs/config.js +85 -0
  10. package/lib/commonjs/config.js.map +1 -0
  11. package/lib/commonjs/errors.js +244 -0
  12. package/lib/commonjs/errors.js.map +1 -0
  13. package/lib/commonjs/hooks.js +257 -0
  14. package/lib/commonjs/hooks.js.map +1 -0
  15. package/lib/commonjs/index.js +244 -0
  16. package/lib/commonjs/index.js.map +1 -0
  17. package/lib/commonjs/internal/autoFlush.js +65 -0
  18. package/lib/commonjs/internal/autoFlush.js.map +1 -0
  19. package/lib/commonjs/internal/base64.js +58 -0
  20. package/lib/commonjs/internal/base64.js.map +1 -0
  21. package/lib/commonjs/internal/bytes.js +32 -0
  22. package/lib/commonjs/internal/bytes.js.map +1 -0
  23. package/lib/commonjs/internal/cloudKitRest.js +527 -0
  24. package/lib/commonjs/internal/cloudKitRest.js.map +1 -0
  25. package/lib/commonjs/internal/enums.js +23 -0
  26. package/lib/commonjs/internal/enums.js.map +1 -0
  27. package/lib/commonjs/internal/googleDriveRest.js +624 -0
  28. package/lib/commonjs/internal/googleDriveRest.js.map +1 -0
  29. package/lib/commonjs/internal/keys.js +139 -0
  30. package/lib/commonjs/internal/keys.js.map +1 -0
  31. package/lib/commonjs/internal/logger.js +29 -0
  32. package/lib/commonjs/internal/logger.js.map +1 -0
  33. package/lib/commonjs/internal/nativeModule.js +125 -0
  34. package/lib/commonjs/internal/nativeModule.js.map +1 -0
  35. package/lib/commonjs/internal/timeout.js +72 -0
  36. package/lib/commonjs/internal/timeout.js.map +1 -0
  37. package/lib/commonjs/package.json +1 -0
  38. package/lib/commonjs/providers/cloudKit.js +398 -0
  39. package/lib/commonjs/providers/cloudKit.js.map +1 -0
  40. package/lib/commonjs/providers/cloudKitBackup.js +86 -0
  41. package/lib/commonjs/providers/cloudKitBackup.js.map +1 -0
  42. package/lib/commonjs/providers/cloudKitEncrypted.js +150 -0
  43. package/lib/commonjs/providers/cloudKitEncrypted.js.map +1 -0
  44. package/lib/commonjs/providers/googleDrive.js +219 -0
  45. package/lib/commonjs/providers/googleDrive.js.map +1 -0
  46. package/lib/commonjs/providers/googleDriveFiles.js +68 -0
  47. package/lib/commonjs/providers/googleDriveFiles.js.map +1 -0
  48. package/lib/commonjs/providers/icloudDocuments.js +121 -0
  49. package/lib/commonjs/providers/icloudDocuments.js.map +1 -0
  50. package/lib/commonjs/providers/icloudKV.js +171 -0
  51. package/lib/commonjs/providers/icloudKV.js.map +1 -0
  52. package/lib/commonjs/providers/icloudKV.web.js +42 -0
  53. package/lib/commonjs/providers/icloudKV.web.js.map +1 -0
  54. package/lib/commonjs/providers/memory.js +201 -0
  55. package/lib/commonjs/providers/memory.js.map +1 -0
  56. package/lib/commonjs/resolvers.js +128 -0
  57. package/lib/commonjs/resolvers.js.map +1 -0
  58. package/lib/commonjs/specs/NativeRNCloudSync.js +14 -0
  59. package/lib/commonjs/specs/NativeRNCloudSync.js.map +1 -0
  60. package/lib/commonjs/store.js +1064 -0
  61. package/lib/commonjs/store.js.map +1 -0
  62. package/lib/commonjs/testing.js +32 -0
  63. package/lib/commonjs/testing.js.map +1 -0
  64. package/lib/commonjs/types.js +86 -0
  65. package/lib/commonjs/types.js.map +1 -0
  66. package/lib/module/config.js +72 -0
  67. package/lib/module/config.js.map +1 -0
  68. package/lib/module/errors.js +231 -0
  69. package/lib/module/errors.js.map +1 -0
  70. package/lib/module/hooks.js +250 -0
  71. package/lib/module/hooks.js.map +1 -0
  72. package/lib/module/index.js +46 -0
  73. package/lib/module/index.js.map +1 -0
  74. package/lib/module/internal/autoFlush.js +62 -0
  75. package/lib/module/internal/autoFlush.js.map +1 -0
  76. package/lib/module/internal/base64.js +53 -0
  77. package/lib/module/internal/base64.js.map +1 -0
  78. package/lib/module/internal/bytes.js +28 -0
  79. package/lib/module/internal/bytes.js.map +1 -0
  80. package/lib/module/internal/cloudKitRest.js +518 -0
  81. package/lib/module/internal/cloudKitRest.js.map +1 -0
  82. package/lib/module/internal/enums.js +18 -0
  83. package/lib/module/internal/enums.js.map +1 -0
  84. package/lib/module/internal/googleDriveRest.js +620 -0
  85. package/lib/module/internal/googleDriveRest.js.map +1 -0
  86. package/lib/module/internal/keys.js +134 -0
  87. package/lib/module/internal/keys.js.map +1 -0
  88. package/lib/module/internal/logger.js +23 -0
  89. package/lib/module/internal/logger.js.map +1 -0
  90. package/lib/module/internal/nativeModule.js +117 -0
  91. package/lib/module/internal/nativeModule.js.map +1 -0
  92. package/lib/module/internal/timeout.js +67 -0
  93. package/lib/module/internal/timeout.js.map +1 -0
  94. package/lib/module/package.json +1 -0
  95. package/lib/module/providers/cloudKit.js +392 -0
  96. package/lib/module/providers/cloudKit.js.map +1 -0
  97. package/lib/module/providers/cloudKitBackup.js +82 -0
  98. package/lib/module/providers/cloudKitBackup.js.map +1 -0
  99. package/lib/module/providers/cloudKitEncrypted.js +146 -0
  100. package/lib/module/providers/cloudKitEncrypted.js.map +1 -0
  101. package/lib/module/providers/googleDrive.js +214 -0
  102. package/lib/module/providers/googleDrive.js.map +1 -0
  103. package/lib/module/providers/googleDriveFiles.js +64 -0
  104. package/lib/module/providers/googleDriveFiles.js.map +1 -0
  105. package/lib/module/providers/icloudDocuments.js +117 -0
  106. package/lib/module/providers/icloudDocuments.js.map +1 -0
  107. package/lib/module/providers/icloudKV.js +165 -0
  108. package/lib/module/providers/icloudKV.js.map +1 -0
  109. package/lib/module/providers/icloudKV.web.js +36 -0
  110. package/lib/module/providers/icloudKV.web.js.map +1 -0
  111. package/lib/module/providers/memory.js +197 -0
  112. package/lib/module/providers/memory.js.map +1 -0
  113. package/lib/module/resolvers.js +120 -0
  114. package/lib/module/resolvers.js.map +1 -0
  115. package/lib/module/specs/NativeRNCloudSync.js +12 -0
  116. package/lib/module/specs/NativeRNCloudSync.js.map +1 -0
  117. package/lib/module/store.js +1061 -0
  118. package/lib/module/store.js.map +1 -0
  119. package/lib/module/testing.js +17 -0
  120. package/lib/module/testing.js.map +1 -0
  121. package/lib/module/types.js +82 -0
  122. package/lib/module/types.js.map +1 -0
  123. package/lib/typescript/commonjs/config.d.ts +33 -0
  124. package/lib/typescript/commonjs/config.d.ts.map +1 -0
  125. package/lib/typescript/commonjs/errors.d.ts +140 -0
  126. package/lib/typescript/commonjs/errors.d.ts.map +1 -0
  127. package/lib/typescript/commonjs/hooks.d.ts +109 -0
  128. package/lib/typescript/commonjs/hooks.d.ts.map +1 -0
  129. package/lib/typescript/commonjs/index.d.ts +37 -0
  130. package/lib/typescript/commonjs/index.d.ts.map +1 -0
  131. package/lib/typescript/commonjs/internal/autoFlush.d.ts +45 -0
  132. package/lib/typescript/commonjs/internal/autoFlush.d.ts.map +1 -0
  133. package/lib/typescript/commonjs/internal/base64.d.ts +12 -0
  134. package/lib/typescript/commonjs/internal/base64.d.ts.map +1 -0
  135. package/lib/typescript/commonjs/internal/bytes.d.ts +12 -0
  136. package/lib/typescript/commonjs/internal/bytes.d.ts.map +1 -0
  137. package/lib/typescript/commonjs/internal/cloudKitRest.d.ts +149 -0
  138. package/lib/typescript/commonjs/internal/cloudKitRest.d.ts.map +1 -0
  139. package/lib/typescript/commonjs/internal/enums.d.ts +10 -0
  140. package/lib/typescript/commonjs/internal/enums.d.ts.map +1 -0
  141. package/lib/typescript/commonjs/internal/googleDriveRest.d.ts +232 -0
  142. package/lib/typescript/commonjs/internal/googleDriveRest.d.ts.map +1 -0
  143. package/lib/typescript/commonjs/internal/keys.d.ts +28 -0
  144. package/lib/typescript/commonjs/internal/keys.d.ts.map +1 -0
  145. package/lib/typescript/commonjs/internal/logger.d.ts +10 -0
  146. package/lib/typescript/commonjs/internal/logger.d.ts.map +1 -0
  147. package/lib/typescript/commonjs/internal/nativeModule.d.ts +29 -0
  148. package/lib/typescript/commonjs/internal/nativeModule.d.ts.map +1 -0
  149. package/lib/typescript/commonjs/internal/timeout.d.ts +36 -0
  150. package/lib/typescript/commonjs/internal/timeout.d.ts.map +1 -0
  151. package/lib/typescript/commonjs/package.json +1 -0
  152. package/lib/typescript/commonjs/providers/cloudKit.d.ts +86 -0
  153. package/lib/typescript/commonjs/providers/cloudKit.d.ts.map +1 -0
  154. package/lib/typescript/commonjs/providers/cloudKitBackup.d.ts +65 -0
  155. package/lib/typescript/commonjs/providers/cloudKitBackup.d.ts.map +1 -0
  156. package/lib/typescript/commonjs/providers/cloudKitEncrypted.d.ts +37 -0
  157. package/lib/typescript/commonjs/providers/cloudKitEncrypted.d.ts.map +1 -0
  158. package/lib/typescript/commonjs/providers/googleDrive.d.ts +35 -0
  159. package/lib/typescript/commonjs/providers/googleDrive.d.ts.map +1 -0
  160. package/lib/typescript/commonjs/providers/googleDriveFiles.d.ts +59 -0
  161. package/lib/typescript/commonjs/providers/googleDriveFiles.d.ts.map +1 -0
  162. package/lib/typescript/commonjs/providers/icloudDocuments.d.ts +101 -0
  163. package/lib/typescript/commonjs/providers/icloudDocuments.d.ts.map +1 -0
  164. package/lib/typescript/commonjs/providers/icloudKV.d.ts +26 -0
  165. package/lib/typescript/commonjs/providers/icloudKV.d.ts.map +1 -0
  166. package/lib/typescript/commonjs/providers/icloudKV.web.d.ts +12 -0
  167. package/lib/typescript/commonjs/providers/icloudKV.web.d.ts.map +1 -0
  168. package/lib/typescript/commonjs/providers/memory.d.ts +90 -0
  169. package/lib/typescript/commonjs/providers/memory.d.ts.map +1 -0
  170. package/lib/typescript/commonjs/resolvers.d.ts +60 -0
  171. package/lib/typescript/commonjs/resolvers.d.ts.map +1 -0
  172. package/lib/typescript/commonjs/specs/NativeRNCloudSync.d.ts +133 -0
  173. package/lib/typescript/commonjs/specs/NativeRNCloudSync.d.ts.map +1 -0
  174. package/lib/typescript/commonjs/store.d.ts +118 -0
  175. package/lib/typescript/commonjs/store.d.ts.map +1 -0
  176. package/lib/typescript/commonjs/testing.d.ts +16 -0
  177. package/lib/typescript/commonjs/testing.d.ts.map +1 -0
  178. package/lib/typescript/commonjs/types.d.ts +367 -0
  179. package/lib/typescript/commonjs/types.d.ts.map +1 -0
  180. package/lib/typescript/module/config.d.ts +33 -0
  181. package/lib/typescript/module/config.d.ts.map +1 -0
  182. package/lib/typescript/module/errors.d.ts +140 -0
  183. package/lib/typescript/module/errors.d.ts.map +1 -0
  184. package/lib/typescript/module/hooks.d.ts +109 -0
  185. package/lib/typescript/module/hooks.d.ts.map +1 -0
  186. package/lib/typescript/module/index.d.ts +37 -0
  187. package/lib/typescript/module/index.d.ts.map +1 -0
  188. package/lib/typescript/module/internal/autoFlush.d.ts +45 -0
  189. package/lib/typescript/module/internal/autoFlush.d.ts.map +1 -0
  190. package/lib/typescript/module/internal/base64.d.ts +12 -0
  191. package/lib/typescript/module/internal/base64.d.ts.map +1 -0
  192. package/lib/typescript/module/internal/bytes.d.ts +12 -0
  193. package/lib/typescript/module/internal/bytes.d.ts.map +1 -0
  194. package/lib/typescript/module/internal/cloudKitRest.d.ts +149 -0
  195. package/lib/typescript/module/internal/cloudKitRest.d.ts.map +1 -0
  196. package/lib/typescript/module/internal/enums.d.ts +10 -0
  197. package/lib/typescript/module/internal/enums.d.ts.map +1 -0
  198. package/lib/typescript/module/internal/googleDriveRest.d.ts +232 -0
  199. package/lib/typescript/module/internal/googleDriveRest.d.ts.map +1 -0
  200. package/lib/typescript/module/internal/keys.d.ts +28 -0
  201. package/lib/typescript/module/internal/keys.d.ts.map +1 -0
  202. package/lib/typescript/module/internal/logger.d.ts +10 -0
  203. package/lib/typescript/module/internal/logger.d.ts.map +1 -0
  204. package/lib/typescript/module/internal/nativeModule.d.ts +29 -0
  205. package/lib/typescript/module/internal/nativeModule.d.ts.map +1 -0
  206. package/lib/typescript/module/internal/timeout.d.ts +36 -0
  207. package/lib/typescript/module/internal/timeout.d.ts.map +1 -0
  208. package/lib/typescript/module/package.json +1 -0
  209. package/lib/typescript/module/providers/cloudKit.d.ts +86 -0
  210. package/lib/typescript/module/providers/cloudKit.d.ts.map +1 -0
  211. package/lib/typescript/module/providers/cloudKitBackup.d.ts +65 -0
  212. package/lib/typescript/module/providers/cloudKitBackup.d.ts.map +1 -0
  213. package/lib/typescript/module/providers/cloudKitEncrypted.d.ts +37 -0
  214. package/lib/typescript/module/providers/cloudKitEncrypted.d.ts.map +1 -0
  215. package/lib/typescript/module/providers/googleDrive.d.ts +35 -0
  216. package/lib/typescript/module/providers/googleDrive.d.ts.map +1 -0
  217. package/lib/typescript/module/providers/googleDriveFiles.d.ts +59 -0
  218. package/lib/typescript/module/providers/googleDriveFiles.d.ts.map +1 -0
  219. package/lib/typescript/module/providers/icloudDocuments.d.ts +101 -0
  220. package/lib/typescript/module/providers/icloudDocuments.d.ts.map +1 -0
  221. package/lib/typescript/module/providers/icloudKV.d.ts +26 -0
  222. package/lib/typescript/module/providers/icloudKV.d.ts.map +1 -0
  223. package/lib/typescript/module/providers/icloudKV.web.d.ts +12 -0
  224. package/lib/typescript/module/providers/icloudKV.web.d.ts.map +1 -0
  225. package/lib/typescript/module/providers/memory.d.ts +90 -0
  226. package/lib/typescript/module/providers/memory.d.ts.map +1 -0
  227. package/lib/typescript/module/resolvers.d.ts +60 -0
  228. package/lib/typescript/module/resolvers.d.ts.map +1 -0
  229. package/lib/typescript/module/specs/NativeRNCloudSync.d.ts +133 -0
  230. package/lib/typescript/module/specs/NativeRNCloudSync.d.ts.map +1 -0
  231. package/lib/typescript/module/store.d.ts +118 -0
  232. package/lib/typescript/module/store.d.ts.map +1 -0
  233. package/lib/typescript/module/testing.d.ts +16 -0
  234. package/lib/typescript/module/testing.d.ts.map +1 -0
  235. package/lib/typescript/module/types.d.ts +367 -0
  236. package/lib/typescript/module/types.d.ts.map +1 -0
  237. package/package.json +186 -0
  238. package/plugin/build/index.d.ts +45 -0
  239. package/plugin/build/index.js +93 -0
  240. package/react-native-cloud-sync.podspec +48 -0
  241. package/src/config.ts +94 -0
  242. package/src/errors.ts +263 -0
  243. package/src/hooks.ts +337 -0
  244. package/src/index.ts +113 -0
  245. package/src/internal/autoFlush.ts +87 -0
  246. package/src/internal/base64.ts +63 -0
  247. package/src/internal/bytes.ts +28 -0
  248. package/src/internal/cloudKitRest.ts +654 -0
  249. package/src/internal/enums.ts +35 -0
  250. package/src/internal/googleDriveRest.ts +765 -0
  251. package/src/internal/keys.ts +160 -0
  252. package/src/internal/logger.ts +23 -0
  253. package/src/internal/nativeModule.ts +149 -0
  254. package/src/internal/timeout.ts +83 -0
  255. package/src/providers/cloudKit.ts +510 -0
  256. package/src/providers/cloudKitBackup.ts +124 -0
  257. package/src/providers/cloudKitEncrypted.ts +175 -0
  258. package/src/providers/googleDrive.ts +251 -0
  259. package/src/providers/googleDriveFiles.ts +117 -0
  260. package/src/providers/icloudDocuments.ts +175 -0
  261. package/src/providers/icloudKV.ts +206 -0
  262. package/src/providers/icloudKV.web.ts +41 -0
  263. package/src/providers/memory.ts +302 -0
  264. package/src/resolvers.ts +133 -0
  265. package/src/specs/NativeRNCloudSync.ts +184 -0
  266. package/src/store.ts +1288 -0
  267. package/src/testing.ts +22 -0
  268. package/src/types.ts +426 -0
package/src/testing.ts ADDED
@@ -0,0 +1,22 @@
1
+ /**
2
+ * Test utilities.
3
+ *
4
+ * Deliberately a real package entry point:
5
+ *
6
+ * import { createMemoryProvider } from 'react-native-cloud-sync/testing'
7
+ *
8
+ * expo-cloudkit ships a comparable mock factory but never exports it from the
9
+ * package (its own source says "Import them directly from 'expo-cloudkit/src/testing'
10
+ * in test environments only") and never mentions it in the README - so in
11
+ * practice nobody finds it. An untested testing helper is not a testing story.
12
+ */
13
+ export {
14
+ createMemoryProvider,
15
+ type Fault,
16
+ type FaultOp,
17
+ type MemoryProvider,
18
+ type MemoryProviderOptions
19
+ } from './providers/memory'
20
+
21
+ export { ErrorCode, CloudSyncError, isCloudSyncError } from './errors'
22
+ export type { AccountStatus, ChangeReason, CloudProvider } from './types'
package/src/types.ts ADDED
@@ -0,0 +1,426 @@
1
+ import type { CloudSyncError } from './errors'
2
+ import type { AutoFlushConfig } from './internal/autoFlush'
3
+
4
+ /**
5
+ * Full account state.
6
+ *
7
+ * Deliberately not a boolean. `react-native-icloud-kit` exposes
8
+ * `isAvailable(): Bool`, which flattens CloudKit's five `CKAccountStatus`
9
+ * values into one bit - so an app cannot tell "signed out" (ask the user to
10
+ * sign in) from "temporarily unavailable" (retry silently) from "could not
11
+ * determine" (do nothing yet). Those three demand different product behaviour.
12
+ */
13
+ export type AccountStatus
14
+ = | 'available'
15
+ | 'noAccount'
16
+ | 'restricted'
17
+ | 'temporarilyUnavailable'
18
+ | 'couldNotDetermine'
19
+
20
+ /** Why a remote-change event fired. Mirrors NSUbiquitousKeyValueStore's reasons. */
21
+ export type ChangeReason
22
+ = | 'serverChange'
23
+ | 'initialSync'
24
+ | 'quotaViolation'
25
+ | 'accountChange'
26
+ | 'unknown'
27
+
28
+ export interface RemoteChangeEvent {
29
+ /** Keys whose values changed. May be empty for `accountChange`/`quotaViolation`. */
30
+ keys: string[]
31
+ reason: ChangeReason
32
+ provider: ProviderName
33
+ }
34
+
35
+ export interface AccountChangeEvent {
36
+ status: AccountStatus
37
+ /**
38
+ * True when the signed-in identity itself changed (a different Apple ID), as
39
+ * opposed to the same account merely becoming available or unavailable.
40
+ *
41
+ * This is the event nobody handles. MagisteriaApp stores an anonymous user id
42
+ * in iCloud and never observes `NSUbiquityIdentityDidChange`, so switching
43
+ * Apple ID silently keeps the previous user's identity - its own TODO records
44
+ * this as "sign out does not always give you a clean guest". Apps should treat
45
+ * `identityChanged: true` as "drop all cached user-scoped state".
46
+ */
47
+ identityChanged: boolean
48
+ provider: ProviderName
49
+ }
50
+
51
+ export interface AssetProgressEvent {
52
+ recordName: string
53
+ fieldName: string
54
+ bytesTransferred: number
55
+ bytesTotal: number
56
+ }
57
+
58
+ /** The providers this package ships. */
59
+ export type { AutoFlushConfig }
60
+
61
+ export type BuiltInProviderName
62
+ = | 'icloudKV'
63
+ | 'cloudKit'
64
+ | 'cloudKitEncrypted'
65
+ | 'googleDrive'
66
+ | 'memory'
67
+
68
+ /**
69
+ * A provider's name.
70
+ *
71
+ * Open on purpose. `registerProvider` is documented as the way to plug in a
72
+ * provider you wrote yourself, but while this was a closed union of the four
73
+ * built-ins that was impossible to express in types - a `'dropbox'` provider
74
+ * needed a cast at every call site, including in `CloudStoreOptions.providers`.
75
+ * The `string & {}` arm keeps editor autocomplete for the built-in names while
76
+ * still accepting any other string.
77
+ */
78
+ export type ProviderName = BuiltInProviderName | (string & {})
79
+
80
+ export type Unsubscribe = () => void
81
+
82
+ /**
83
+ * The contract every provider implements. The facade in `store.ts` is written
84
+ * against this and nothing else, which is what makes providers swappable and
85
+ * makes the in-memory test double a first-class provider rather than a mock.
86
+ */
87
+ export interface CloudProvider {
88
+ readonly name: ProviderName
89
+
90
+ /**
91
+ * Whether this provider can currently be used. Cheap and non-throwing, so it
92
+ * is safe to call on a render path.
93
+ */
94
+ isAvailable: () => Promise<boolean>
95
+
96
+ getAccountStatus: () => Promise<AccountStatus>
97
+
98
+ /**
99
+ * Resolves `null` if and only if the key does not exist. Every other failure
100
+ * rejects with a {@link CloudSyncError}. See `errors.ts` for why.
101
+ */
102
+ getItem: (key: string) => Promise<string | null>
103
+
104
+ /**
105
+ * Like {@link getItem}, but also reports the server's own last-modified time.
106
+ *
107
+ * Optional because not every backing store knows one - `NSUbiquitousKeyValueStore`
108
+ * exposes no per-key timestamp at all. Where a provider *does* know (CloudKit's
109
+ * `modified.timestamp`, Drive's `modifiedTime`, both one query parameter away),
110
+ * implementing this lets {@link resolveByModifiedAt} order candidates without
111
+ * the app having to embed a timestamp inside its own payload.
112
+ */
113
+ getItemWithMeta?: (key: string) => Promise<ItemWithMeta | null>
114
+
115
+ setItem: (key: string, value: string) => Promise<void>
116
+
117
+ removeItem: (key: string) => Promise<void>
118
+
119
+ getAllKeys: () => Promise<string[]>
120
+
121
+ /**
122
+ * Reads many keys in one go. Optional: the store falls back to sequential
123
+ * {@link getItem} calls when a provider does not implement it.
124
+ *
125
+ * Worth implementing whenever the backend has a batch endpoint - CloudKit Web
126
+ * Services' `/records/lookup` and `/records/modify` both take arrays, so the
127
+ * difference between this and a loop is one request against N.
128
+ */
129
+ multiGet?: (keys: string[]) => Promise<(string | null)[]>
130
+
131
+ /** Writes many key/value pairs in one go. Optional, same fallback rule. */
132
+ multiSet?: (entries: [string, string][]) => Promise<void>
133
+
134
+ /** Removes many keys in one go. Optional, same fallback rule. */
135
+ multiRemove?: (keys: string[]) => Promise<void>
136
+
137
+ /**
138
+ * Total and used bytes for this account, when the backend reports them.
139
+ * Optional - `NSUbiquitousKeyValueStore` has no usage API.
140
+ */
141
+ getQuota?: () => Promise<QuotaInfo | null>
142
+
143
+ /**
144
+ * Drops any state cached for the *previous* account.
145
+ *
146
+ * Called by the store when an `identityChanged` account event arrives.
147
+ * Memoised Drive file ids and CloudKit reachability answers belong to whoever
148
+ * was signed in when they were recorded; serving them to the next user is a
149
+ * cross-account data leak.
150
+ */
151
+ clearCaches?: () => void
152
+
153
+ onRemoteChange?: (listener: (e: RemoteChangeEvent) => void) => Unsubscribe
154
+
155
+ onAccountChange?: (listener: (e: AccountChangeEvent) => void) => Unsubscribe
156
+ }
157
+
158
+ /** A value plus whatever metadata the provider could report alongside it. */
159
+ export interface ItemWithMeta {
160
+ value: string
161
+ /** Server-reported last modification, epoch millis, when the provider knows one. */
162
+ modifiedAt?: number
163
+ }
164
+
165
+ /** Account storage usage, for providers that report it. */
166
+ export interface QuotaInfo {
167
+ /** Bytes currently used, or undefined when the backend does not say. */
168
+ usedBytes?: number
169
+ /** Total bytes available, or undefined for an unlimited/unreported quota. */
170
+ totalBytes?: number
171
+ provider: ProviderName
172
+ }
173
+
174
+ /** Byte thresholds that decide which backing store a value lands in. */
175
+ export interface TieringConfig {
176
+ /**
177
+ * At or below this, values go to the iCloud key-value store.
178
+ *
179
+ * Apple's hard limits are 1 MB total / 1 MB per key / 1024 keys, but the
180
+ * *total* is the one that bites - a handful of large values silently starves
181
+ * every other key. 64 KB keeps the KV store for what it is good at (settings,
182
+ * small identifiers) and pushes real payloads to CloudKit records.
183
+ */
184
+ kvMaxBytes: number
185
+ /**
186
+ * At or below this, values go in a CKRecord field. CloudKit's documented
187
+ * record ceiling is 1 MB excluding assets; 900 KB leaves room for the record's
188
+ * own metadata.
189
+ */
190
+ recordMaxBytes: number
191
+ }
192
+
193
+ export const DEFAULT_TIERING: TieringConfig = {
194
+ kvMaxBytes: 64 * 1024,
195
+ recordMaxBytes: 900 * 1024,
196
+ }
197
+
198
+ export interface OutboxEntry {
199
+ key: string
200
+ value: string | null
201
+ provider: ProviderName
202
+ attempts: number
203
+ /** Epoch millis of the next attempt. */
204
+ nextAttemptAt: number
205
+ enqueuedAt: number
206
+ /**
207
+ * The error code of the most recent failed attempt, so a "pending sync" UI
208
+ * can say *why* something is still queued rather than only that it is.
209
+ */
210
+ lastErrorCode?: string
211
+ }
212
+
213
+ /** Why the store gave up on a queued write. Reported through {@link CloudStoreOptions.onDropped}. */
214
+ /**
215
+ * - `notRetryable` - the failure stopped being retryable; the user has to act on it.
216
+ * - `tooManyAttempts` - {@link CloudStoreOptions.outboxMaxAttempts} was reached.
217
+ * - `expired` - it sat in the queue longer than {@link CloudStoreOptions.outboxMaxAgeMs}.
218
+ * - `queueFull` - the queue hit its cap and this was the oldest entry.
219
+ * - `accountChanged` - a different account signed in, so it belongs to nobody now.
220
+ * - `discarded` - `discardPendingWrites` removed it.
221
+ */
222
+ export type DropReason
223
+ = | 'notRetryable'
224
+ | 'tooManyAttempts'
225
+ | 'expired'
226
+ | 'queueFull'
227
+ | 'accountChanged'
228
+ | 'discarded'
229
+
230
+ export interface DroppedWrite {
231
+ entry: OutboxEntry
232
+ reason: DropReason
233
+ /** The failure that caused it, when there was one. */
234
+ error?: CloudSyncError
235
+ }
236
+
237
+ /**
238
+ * How a write is distributed across the configured providers.
239
+ *
240
+ * - `failover` - write to the first available provider only. The rest are read
241
+ * fallbacks. Cheapest, and right when the providers are alternatives.
242
+ * - `mirror` - write to every available provider. Costs one request per
243
+ * provider, and is what makes a value written on an iPhone readable on
244
+ * Android: the Apple-only providers cannot be reached from there, so unless
245
+ * something also wrote to Drive, there is nothing for Android to find.
246
+ *
247
+ * Reads fall through the list in both modes.
248
+ */
249
+ export type WriteMode = 'failover' | 'mirror'
250
+
251
+ /** One provider's copy of a key, as seen during a resolving read. */
252
+ export interface ResolveCandidate {
253
+ provider: ProviderName
254
+ value: string
255
+ /**
256
+ * The server's own last-modified time in epoch millis, when the provider
257
+ * reported one (see {@link CloudProvider.getItemWithMeta}).
258
+ *
259
+ * This is what {@link resolveByModifiedAt} orders on, and it is why that
260
+ * resolver works on payloads the app never had to instrument.
261
+ */
262
+ modifiedAt?: number
263
+ }
264
+
265
+ /**
266
+ * Picks the winner when providers disagree.
267
+ *
268
+ * The store holds opaque strings, so it cannot know which copy is newer - only
269
+ * the app knows what its values mean. Returning `null` means "none of these",
270
+ * which reads as absent.
271
+ */
272
+ export type ResolveFn = (candidates: ResolveCandidate[]) => string | null
273
+
274
+ export interface CloudStoreOptions {
275
+ /**
276
+ * Providers in preference order.
277
+ *
278
+ * Reads fall through this list until a value is found. Writes go to the first
279
+ * available provider, or to all of them - see {@link writeMode}.
280
+ */
281
+ providers: ProviderName[]
282
+ /**
283
+ * Default `failover`.
284
+ *
285
+ * Use `mirror` when the same data has to be reachable from a platform where
286
+ * the preferred provider does not exist.
287
+ */
288
+ writeMode?: WriteMode
289
+ /**
290
+ * How a read picks a value when more than one provider holds the key.
291
+ *
292
+ * Without this, `getItem` returns the first non-null value in provider order
293
+ * and stops. That is cheap and correct when only one device population
294
+ * writes - but it silently serves stale data as soon as writes come from
295
+ * both sides. An Apple device reading `['icloudKV', 'googleDrive']` always
296
+ * finds *something* in iCloud, so a newer value written from Android via
297
+ * Drive is never even looked at.
298
+ *
299
+ * Supplying this makes a read consult every available provider and hand you
300
+ * the candidates. {@link resolveByTimestamp} covers the usual case.
301
+ */
302
+ resolve?: ResolveFn
303
+ /**
304
+ * After a resolving read, write the winner back to providers that disagreed.
305
+ *
306
+ * Default true when {@link resolve} is set. This is what actually makes two
307
+ * populations converge: without it, the losing store keeps its old value and
308
+ * every read pays to resolve again forever.
309
+ *
310
+ * Best-effort - a failed repair never fails the read.
311
+ */
312
+ repairOnRead?: boolean
313
+ tiering?: TieringConfig | 'auto' | 'off'
314
+ /**
315
+ * Persist failed writes and retry them with backoff.
316
+ *
317
+ * Default true. With it off, a write made while offline is lost - which is
318
+ * exactly the documented behaviour of react-native-cloud-storage today
319
+ * ("the OS will not throw an error ... you'll need to check for an internet
320
+ * connection before handing data to" it).
321
+ */
322
+ outbox?: boolean
323
+ /**
324
+ * Hard cap on queued writes. Default 1000.
325
+ *
326
+ * An unbounded queue is a slow memory and storage leak: every `enqueue`
327
+ * rewrites the whole JSON blob, so an app that stays offline long enough
328
+ * degrades its own write path. When the cap is hit the oldest entry is
329
+ * dropped and reported through {@link onDropped}, so the loss is visible
330
+ * rather than silent.
331
+ */
332
+ outboxMaxEntries?: number
333
+ /**
334
+ * Give up on a queued write after this many failed attempts. Default 12,
335
+ * which with the capped exponential backoff is roughly an hour of retrying.
336
+ */
337
+ outboxMaxAttempts?: number
338
+ /**
339
+ * Give up on a queued write older than this. Default 7 days.
340
+ *
341
+ * Time matters independently of attempt count: an app opened twice in a month
342
+ * accrues almost no attempts, and re-sending a fortnight-old value over
343
+ * whatever the user has done since is rarely what they want.
344
+ */
345
+ outboxMaxAgeMs?: number
346
+ /** Called whenever a queued write is abandoned, with the reason. */
347
+ onDropped?: (dropped: DroppedWrite) => void
348
+ /**
349
+ * Drain the outbox automatically, instead of leaving `flushOutbox()` entirely
350
+ * to the caller. Off by default; pass `true` for the defaults.
351
+ *
352
+ * A durable queue with no trigger is only half a feature - every retryable
353
+ * failure is captured correctly and then waits for someone to remember. This
354
+ * flushes on app foreground and on a slow timer, which is where nearly every
355
+ * app was calling it by hand.
356
+ *
357
+ * Not network-aware, on purpose: that needs NetInfo, and adding a dependency
358
+ * every consumer must install to save one line in the ones that want it is a
359
+ * bad trade. Call `flushOutbox()` from your own reconnect listener too if you
360
+ * have one.
361
+ */
362
+ autoFlush?: boolean | AutoFlushConfig
363
+ /**
364
+ * How long an `isAvailable()` answer is reused across operations. Default 3000.
365
+ *
366
+ * The store asks every provider before every operation, and for `icloudKV`
367
+ * that is a bridge hop while for `googleDrive` it invokes the host's
368
+ * `getAccessToken`. Unmemoised, a loop over 100 keys cost 100+ probes on top
369
+ * of the actual work. Set to 0 to probe every time.
370
+ */
371
+ availabilityTtlMs?: number
372
+ /**
373
+ * Transforms values on the way out and back on the way in - the seam for
374
+ * encrypting at rest.
375
+ *
376
+ * Drive's `appDataFolder` is plaintext to anything holding the account's OAuth
377
+ * token, and this package deliberately ships no crypto of its own (key
378
+ * management is the app's problem, and bundling a cipher would make it look
379
+ * solved). Supplying a codec is how you close that gap with a library you
380
+ * chose.
381
+ *
382
+ * Applied to values only, never to keys - `getAllKeys()`, tiering and read
383
+ * repair all need cleartext keys to work.
384
+ *
385
+ * Encoding runs *before* tiering picks a destination, so a value is routed by
386
+ * the size it will actually occupy rather than by its plaintext size. That is
387
+ * the correct behaviour, and it means a codec that inflates its input makes
388
+ * your effective {@link TieringConfig.kvMaxBytes} smaller than the number
389
+ * says.
390
+ */
391
+ codec?: ValueCodec
392
+ /**
393
+ * Reject keys that cannot round-trip through every configured provider.
394
+ * Default true.
395
+ *
396
+ * One key string has to be a `NSUbiquitousKeyValueStore` key, a CloudKit
397
+ * `recordName` and a Drive filename at once, and those three disagree about
398
+ * what is legal. Without this check an invalid `recordName` comes back from
399
+ * CloudKit as `BAD_REQUEST`, which maps to `ERR_CONTAINER_MISCONFIGURED` and
400
+ * sends you looking at your entitlements instead of at your key.
401
+ */
402
+ validateKeys?: boolean
403
+ /**
404
+ * Abandon a single provider operation that has not settled in this long,
405
+ * with {@link ErrorCode.TIMEOUT}. Off by default.
406
+ *
407
+ * React Native's `fetch` has no default timeout and neither does CloudKit's
408
+ * native stack, so a socket that never answers hangs the operation forever -
409
+ * including `isAvailable()`, which the store calls before everything else.
410
+ * A timeout is classified as retryable, so with the outbox on, a hung write
411
+ * is queued rather than lost.
412
+ */
413
+ timeoutMs?: number
414
+ onError?: (e: CloudSyncError) => void
415
+ }
416
+
417
+ /**
418
+ * A two-way value transform, applied at the boundary between the store and its
419
+ * providers. See {@link CloudStoreOptions.codec}.
420
+ */
421
+ export interface ValueCodec {
422
+ /** Called with the app's value; the result is what the provider stores. */
423
+ encode: (value: string, key: string) => Promise<string> | string
424
+ /** Called with what the provider returned; the result is what the app sees. */
425
+ decode: (value: string, key: string) => Promise<string> | string
426
+ }