@gfean/react-native-bundle-drop 0.4.2 → 0.4.4

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 (111) hide show
  1. package/BundleDropExpo.podspec +21 -0
  2. package/README.md +339 -74
  3. package/android/src/main/java/com/bundledrop/BundleDropNativePaths.kt +33 -3
  4. package/app.plugin.js +3 -0
  5. package/expo/android/build.gradle +159 -0
  6. package/expo/android/src/main/AndroidManifest.xml +1 -0
  7. package/expo/android/src/main/java/com/bundledrop/expo/BundleDropExpoConfiguration.kt +35 -0
  8. package/expo/android/src/main/java/com/bundledrop/expo/BundleDropExpoIdentityModule.kt +30 -0
  9. package/expo/android/src/main/java/com/bundledrop/expo/BundleDropExpoPackage.kt +29 -0
  10. package/expo/android/src/main/java/com/bundledrop/expo/BundleDropExpoReactNativeHostHandler.kt +16 -0
  11. package/expo/bundle-drop-expo-gradle-plugin/build.gradle +31 -0
  12. package/expo/bundle-drop-expo-gradle-plugin/src/main/groovy/com/bundledrop/gradle/BundleDropExpoPlugin.groovy +83 -0
  13. package/expo/bundle-drop-expo-gradle-plugin/src/main/groovy/com/bundledrop/gradle/GenerateBundleDropBuildIdentityTask.groovy +57 -0
  14. package/expo/ios/Sources/BundleDropExpoIdentity.m +31 -0
  15. package/expo/ios/Sources/BundleDropExpoReactDelegateHandler.swift +24 -0
  16. package/expo-module.config.json +19 -0
  17. package/ios/BundleDropLocator.swift +7 -1
  18. package/lib/CLI/cli.d.ts +1 -2
  19. package/lib/CLI/cli.js +126 -31
  20. package/lib/CLI/logo.d.ts +9 -0
  21. package/lib/CLI/logo.js +26 -0
  22. package/lib/CLI/scripts/aipowered/apply-setup-plan.d.ts +12 -0
  23. package/lib/CLI/scripts/aipowered/apply-setup-plan.js +55 -0
  24. package/lib/CLI/scripts/aipowered/backend-client.d.ts +6 -1
  25. package/lib/CLI/scripts/aipowered/backend-client.js +25 -2
  26. package/lib/CLI/scripts/aipowered/init-project-config.d.ts +17 -0
  27. package/lib/CLI/scripts/aipowered/init-project-config.js +400 -0
  28. package/lib/CLI/scripts/aipowered/scanner.d.ts +10 -1
  29. package/lib/CLI/scripts/aipowered/scanner.js +274 -5
  30. package/lib/CLI/scripts/aipowered/types.d.ts +39 -0
  31. package/lib/CLI/scripts/aipowered/validate-plan.d.ts +12 -0
  32. package/lib/CLI/scripts/aipowered/validate-plan.js +76 -1
  33. package/lib/CLI/scripts/doctor.d.ts +17 -0
  34. package/lib/CLI/scripts/doctor.js +412 -0
  35. package/lib/CLI/scripts/expo/build-receipt.d.ts +26 -0
  36. package/lib/CLI/scripts/expo/build-receipt.js +223 -0
  37. package/lib/CLI/scripts/expo/configure-expo.d.ts +28 -0
  38. package/lib/CLI/scripts/expo/configure-expo.js +268 -0
  39. package/lib/CLI/scripts/expo/eas-build-proof.d.ts +22 -0
  40. package/lib/CLI/scripts/expo/eas-build-proof.js +116 -0
  41. package/lib/CLI/scripts/expo/package-manager.d.ts +11 -0
  42. package/lib/CLI/scripts/expo/package-manager.js +84 -0
  43. package/lib/CLI/scripts/expo/write-build-receipt.d.ts +25 -0
  44. package/lib/CLI/scripts/expo/write-build-receipt.js +325 -0
  45. package/lib/CLI/scripts/expo/write-eas-build-receipt.d.ts +8 -0
  46. package/lib/CLI/scripts/expo/write-eas-build-receipt.js +71 -0
  47. package/lib/CLI/scripts/init-config.d.ts +18 -1
  48. package/lib/CLI/scripts/init-config.js +29 -9
  49. package/lib/CLI/scripts/init-metro-config.d.ts +7 -0
  50. package/lib/CLI/scripts/init-metro-config.js +28 -8
  51. package/lib/CLI/scripts/login-cli.js +17 -3
  52. package/lib/CLI/scripts/post-init.d.ts +6 -1
  53. package/lib/CLI/scripts/post-init.js +6 -33
  54. package/lib/CLI/scripts/upload-cli.d.ts +1 -0
  55. package/lib/CLI/scripts/upload-cli.js +106 -36
  56. package/lib/context.d.ts +0 -2
  57. package/lib/context.js +19 -3
  58. package/lib/expo/buildIdentity.d.ts +15 -0
  59. package/lib/expo/buildIdentity.js +201 -0
  60. package/lib/expo/buildReceipt.d.ts +42 -0
  61. package/lib/expo/buildReceipt.js +272 -0
  62. package/lib/expo/config.d.ts +7 -0
  63. package/lib/expo/config.js +43 -0
  64. package/lib/expo/configCache.d.ts +1 -0
  65. package/lib/expo/configCache.js +20 -0
  66. package/lib/expo/errors.d.ts +6 -0
  67. package/lib/expo/errors.js +11 -0
  68. package/lib/expo/expoUpdatesOwnership.d.ts +13 -0
  69. package/lib/expo/expoUpdatesOwnership.js +22 -0
  70. package/lib/expo/exportExpoProject.d.ts +21 -0
  71. package/lib/expo/exportExpoProject.js +125 -0
  72. package/lib/expo/exportValidation.d.ts +11 -0
  73. package/lib/expo/exportValidation.js +115 -0
  74. package/lib/expo/index.d.ts +18 -0
  75. package/lib/expo/index.js +25 -0
  76. package/lib/expo/localModules.d.ts +4 -0
  77. package/lib/expo/localModules.js +51 -0
  78. package/lib/expo/nativeIdentity.d.ts +1 -0
  79. package/lib/expo/nativeIdentity.js +17 -0
  80. package/lib/expo/projectType.d.ts +7 -0
  81. package/lib/expo/projectType.js +200 -0
  82. package/lib/expo/runtimeVersion.d.ts +13 -0
  83. package/lib/expo/runtimeVersion.js +45 -0
  84. package/lib/expo/types.d.ts +15 -0
  85. package/lib/expo/types.js +2 -0
  86. package/lib/fs/userProperties.d.ts +0 -2
  87. package/lib/fs/userProperties.js +0 -3
  88. package/lib/index.d.ts +1 -1
  89. package/lib/index.js +1 -2
  90. package/lib/loadConfig.d.ts +17 -5
  91. package/lib/loadConfig.js +2 -19
  92. package/lib/metro.d.ts +17 -0
  93. package/lib/metro.js +57 -0
  94. package/lib/native/bundleDropNative.d.ts +2 -0
  95. package/lib/native/bundleDropNative.js +9 -1
  96. package/lib/runtime/service.js +12 -1
  97. package/lib/scripts/bundle.d.ts +2 -2
  98. package/lib/scripts/bundle.js +30 -99
  99. package/lib/scripts/canonicalArtifact.d.ts +30 -0
  100. package/lib/scripts/canonicalArtifact.js +212 -0
  101. package/lib/scripts/download-bundle.js +1 -1
  102. package/lib/scripts/exportProject.d.ts +41 -0
  103. package/lib/scripts/exportProject.js +82 -0
  104. package/package.json +74 -55
  105. package/plugin/constants.js +9 -0
  106. package/plugin/expoUpdates.js +131 -0
  107. package/plugin/index.js +11 -0
  108. package/plugin/markers.js +31 -0
  109. package/plugin/withBundleDrop.js +36 -0
  110. package/plugin/xcodeBuildPhase.js +77 -0
  111. package/react-native.config.js +20 -0
@@ -0,0 +1,21 @@
1
+ require "json"
2
+
3
+ package = JSON.parse(File.read(File.join(__dir__, "package.json")))
4
+ native_version = package["nativeVersion"] || package["version"]
5
+
6
+ Pod::Spec.new do |s|
7
+ s.name = "BundleDropExpo"
8
+ s.version = native_version
9
+ s.summary = "Expo startup adapter for Bundle Drop"
10
+ s.homepage = package["homepage"]
11
+ s.license = package["license"]
12
+ s.authors = package["author"]
13
+ s.source = { :git => ".git", :tag => "#{s.version}" }
14
+
15
+ s.platforms = { :ios => "15.1" }
16
+ s.source_files = "expo/ios/Sources/**/*.{h,m,mm,swift}"
17
+ s.static_framework = true
18
+ s.swift_version = "5.9"
19
+ s.dependency "BundleDrop"
20
+ s.dependency "ExpoModulesCore"
21
+ end
package/README.md CHANGED
@@ -1,4 +1,4 @@
1
- # BundleDrop
1
+ # Bundle Drop
2
2
 
3
3
  [![npm version](https://img.shields.io/npm/v/%40gfean%2Freact-native-bundle-drop?color=2b7fff&label=npm)](https://www.npmjs.com/package/@gfean/react-native-bundle-drop)
4
4
  [![license](https://img.shields.io/badge/license-ISC-84cc16)](#license)
@@ -6,124 +6,309 @@
6
6
  [![docs](https://img.shields.io/badge/docs-bundledrop.app%2Fdocs-0f766e)](https://bundledrop.app/docs)
7
7
  [![dashboard](https://img.shields.io/badge/dashboard-developer.bundledrop.app-111827)](https://developer.bundledrop.app)
8
8
 
9
- Deploy React Native updates instantly — skip App Store and Play Store delays entirely.
9
+ **Ship reliable over-the-air updates to Expo and bare React Native apps.**
10
10
 
11
- Drop-in OTA solution for bare React Native apps.
11
+ Bundle Drop delivers JavaScript and asset updates to compatible iOS and Android
12
+ binaries, with channel-based releases, targeted rollouts, rollback safety, and
13
+ patch-sized downloads.
12
14
 
13
- [Website](https://bundledrop.app) • [Docs](https://bundledrop.app/docs) • [Dashboard](https://developer.bundledrop.app)
15
+ [Website](https://bundledrop.app) • [Docs](https://bundledrop.app/docs) • [Dashboard](https://developer.bundledrop.app) • [Coming from CodePush?](https://bundledrop.app/codepush-alternative)
14
16
 
15
17
  ---
16
18
 
17
- ## Why BundleDrop?
19
+ ## Why Bundle Drop?
18
20
 
19
- Shipping a small fix should not require a full mobile release.
21
+ Shipping a JavaScript or asset fix should not always require a new native build.
20
22
 
21
- BundleDrop lets you ship updates instantly, directly to your users:
22
- - push JavaScript updates instantly
23
- - roll out changes gradually
24
- - target specific channels or cohorts
25
- - rollback safely when needed
26
- - manage releases from a dedicated dashboard
23
+ | Native release workflow | With Bundle Drop |
24
+ | --- | --- |
25
+ | Rebuild the app for every JavaScript or asset change. | Publish OTA-compatible changes from your machine or CI. |
26
+ | Wait for users to install the next store version. | Compatible devices can receive an update on their next check. |
27
+ | Leave a faulty release active until another binary ships. | Stop a rollout or return to a verified bundle quickly. |
27
28
 
28
- Built for production React Native apps.
29
+ Bundle Drop only delivers updates that match the installed app's native and
30
+ runtime identity. Native changes still require a new App Store or Play Store build.
29
31
 
30
32
  ---
31
33
 
32
- ## What You Can Do
34
+ ## Features
35
+
36
+ - **Expo and bare React Native support** — use the Expo config plugin or native
37
+ React Native autolinking.
38
+ - **Channel-based distribution** — ship to `develop`, `production`, `beta`, or any channel you define.
39
+ - **Targeted rollouts** — stage releases and target specific cohorts with user properties.
40
+ - **Rollback safety** — every install is a verified, immutable bundle; rollback is a local pointer switch.
41
+ - **Hybrid OTA transport** — keep full-bundle integrity while supported devices download patch-sized changes.
42
+ - **Runtime gating** — updates only reach compatible native binaries.
43
+ - **Observability metadata** — bundle hashes and source maps keep crash reports attributable to the correct release.
44
+ - **CI/CD support** — upload with a Personal Access Token from any pipeline.
45
+
46
+ ## Compatibility
47
+
48
+ | Surface | Supported versions |
49
+ | --- | --- |
50
+ | Expo | SDK 54, 55, 56, and 57 |
51
+ | Bare React Native | React Native 0.71 and newer |
52
+ | Platforms | iOS and Android |
53
+ | Architectures | Legacy architecture and New Architecture |
54
+ | Node.js | 20.19.4 or newer |
55
+ | React | 17 or newer |
33
56
 
34
- - ship production hotfixes in seconds
35
- - release to `General`, `Beta`, or custom channels
36
- - target users with dynamic properties
37
- - control when updates are applied
38
- - integrate with CI/CD pipelines
57
+ ## Installation
39
58
 
40
- ---
59
+ ### Expo
41
60
 
42
- ## Installation
61
+ Install the package with Expo's version-aware installer:
62
+
63
+ ```bash
64
+ npx expo install @gfean/react-native-bundle-drop
65
+ ```
66
+
67
+ Bundle Drop's setup command registers the config plugin and preserves your existing
68
+ Expo Metro configuration.
69
+
70
+ ### Bare React Native
71
+
72
+ Install with your package manager:
43
73
 
44
74
  ```bash
45
75
  npm install @gfean/react-native-bundle-drop
76
+ # or
77
+ yarn add @gfean/react-native-bundle-drop
46
78
  ```
47
79
 
80
+ Then install the iOS pod:
81
+
48
82
  ```bash
49
83
  cd ios && pod install
50
84
  ```
51
85
 
52
- ---
86
+ React Native autolinking handles the package on both platforms. The setup command
87
+ adds the app-entry integration that allows a Release build to start an installed OTA.
53
88
 
54
- ## Quick Start
89
+ ## First-Time Setup
55
90
 
56
- ### 1. Connect your project
91
+ Run these commands from your app's project root:
57
92
 
58
93
  ```bash
59
94
  npx bundle-drop login
95
+ npx bundle-drop doctor
96
+ ```
97
+
98
+ `login` signs you in, creates `bundle.drop.config.js` when needed, detects Expo or
99
+ bare React Native, previews the integration changes, and completes setup. `doctor`
100
+ then validates configuration, runtime identity, native integration, and startup
101
+ ownership.
102
+
103
+ Run `init` when you need to review or rerun setup. You can force project detection
104
+ for unusual repository layouts:
105
+
106
+ ```bash
60
107
  npx bundle-drop init
108
+ npx bundle-drop init --project-type expo
109
+ npx bundle-drop init --project-type bare
61
110
  ```
62
111
 
63
- ### 2. Bootstrap BundleDrop in your app
112
+ Run `npx bundle-drop doctor` again after changing native integration, Metro, Expo
113
+ configuration, or runtime versions.
64
114
 
65
- ```ts
115
+ ## Initialize the Runtime
116
+
117
+ Call `BundleDrop.init` once, as early as possible in the app process.
118
+
119
+ ### Expo Router
120
+
121
+ Initialize in `app/_layout.tsx`, before rendering the root layout:
122
+
123
+ ```tsx
66
124
  import { BundleDrop } from '@gfean/react-native-bundle-drop';
125
+ import { Stack } from 'expo-router';
67
126
 
68
127
  BundleDrop.init({
69
128
  enabled: !__DEV__,
70
129
  environment: __DEV__ ? 'development' : 'production',
130
+ channelName: 'develop',
71
131
  policy: 'on-next-launch',
72
- channelName: 'General',
73
132
  });
133
+
134
+ export default function RootLayout() {
135
+ return <Stack />;
136
+ }
74
137
  ```
75
138
 
76
- ### 3. Ship an update
139
+ ### Conventional React Native entrypoint
140
+
141
+ Initialize near the top of your entry file, before registering the root component:
142
+
143
+ ```tsx
144
+ import { AppRegistry } from 'react-native';
145
+ import { BundleDrop } from '@gfean/react-native-bundle-drop';
146
+
147
+ import App from './App';
148
+ import { name as appName } from './app.json';
149
+
150
+ BundleDrop.init({
151
+ enabled: !__DEV__,
152
+ environment: __DEV__ ? 'development' : 'production',
153
+ channelName: 'develop',
154
+ policy: 'on-next-launch',
155
+ });
156
+
157
+ AppRegistry.registerComponent(appName, () => App);
158
+ ```
159
+
160
+ ## Expo Builds and Development
161
+
162
+ Bundle Drop needs its native integration in the installed app. Expo Go does not
163
+ contain that native adapter, so the SDK remains disabled there and your app can keep
164
+ using Expo Go for normal development.
165
+
166
+ Debug builds and development clients also keep Metro as the JavaScript authority;
167
+ they do not start an installed OTA bundle. Test the OTA lifecycle with a non-Debug
168
+ Release build.
169
+
170
+ For managed/CNG projects, setup can leave `ios/` and `android/` absent. The config
171
+ plugin generates the native integration during a later prebuild, `expo run:*`, or
172
+ EAS Build. Typical local Release builds are:
77
173
 
78
174
  ```bash
79
- npx bundle-drop upload android --version 1.2.3 --channel General
80
- npx bundle-drop upload ios --plist-file ios/Info.plist --channel General
175
+ npx expo run:ios --configuration Release
176
+ npx expo run:android --variant release
81
177
  ```
82
178
 
83
- Use `--token` in CI/CD pipelines.
179
+ For remote builds, use your normal EAS profiles:
84
180
 
85
- ---
181
+ ```bash
182
+ eas build --platform ios
183
+ eas build --platform android
184
+ ```
86
185
 
87
- ## Update Policies
186
+ With the default literal runtime configuration, the plugin embeds the platform's
187
+ literal in the native build and Expo uploads resolve that same literal directly from
188
+ `bundle.drop.config.js`. This normal workflow does not require a build receipt.
88
189
 
89
- Choose how updates are applied:
190
+ An advanced Expo project can explicitly make its Expo runtime policy authoritative
191
+ with `runtimeVersion: { source: 'expo' }`. In that opt-in mode, uploads require an
192
+ exact receipt from the matching local native build. For a remote EAS build, create an
193
+ authenticated receipt from the completed build and pass the returned path to upload:
90
194
 
91
- - `manual`: check only, no automatic apply
92
- - `immediate`: download and apply right away
93
- - `on-next-launch`: stage now, apply on next launch
195
+ ```bash
196
+ npx bundle-drop eas-receipt ios --build-id <eas-build-id>
197
+ npx bundle-drop upload ios --channel develop --build-receipt <receipt-path>
198
+ ```
94
199
 
95
- `on-next-launch` is the safest default for most apps.
200
+ Rebuild the native app whenever the config plugin, native dependencies, permissions,
201
+ or runtime compatibility boundary changes.
96
202
 
97
- ## Hybrid OTA Delivery
203
+ ### `expo-updates` startup ownership
204
+
205
+ An active `expo-updates` installation can also own native startup, so it cannot be
206
+ active in the same binary as Bundle Drop. Setup and `doctor` stop when they detect
207
+ that conflict. To migrate intentionally, review the proposed changes and run:
208
+
209
+ ```bash
210
+ npx bundle-drop init --project-type expo --migrate-expo-updates
211
+ ```
98
212
 
99
- BundleDrop installs complete immutable bundle folders, identified by a canonical
100
- `bundleHash` for the full reconstructed file tree. Patch transports are only a
101
- download optimization: the SDK reconstructs a complete target folder, validates
102
- the manifest contract in JS, verifies file hashes/sizes with native batch
103
- verification, then promotes `bundle-drop/bundles/{bundleHash}`.
104
- The SDK always supports `asset-only-v1` patch sets and advertises
105
- `xdelta3-vcdiff` when native xdelta support passes its probe.
213
+ This removes the active `expo-updates` integration and requires a new native binary.
214
+ Do not publish a Bundle Drop update until that replacement binary has been built and
215
+ distributed.
106
216
 
107
- The current production manifest contract is `manifestVersion: 1`. This is not a
108
- legacy compatibility mode; it is the only accepted canonical manifest after the
109
- hard shift. `jsBundleHash` is retained as metadata only.
217
+ ## Runtime Versions
110
218
 
111
- When patch transport is unavailable or fails, the SDK falls back to the signed
112
- full ZIP. Rollback remains a local pointer switch between verified bundle hashes.
219
+ `bundle.drop.config.js` defines literal runtime versions shared by Expo and bare
220
+ React Native projects:
113
221
 
114
- ---
222
+ ```js
223
+ module.exports = {
224
+ // ...project configuration
225
+ runtimeVersion: {
226
+ ios: '1.0.0',
227
+ android: '1.0.0',
228
+ },
229
+ };
230
+ ```
115
231
 
116
- ## Why Not App Store Updates?
232
+ Keep a platform's literal unchanged for OTA-compatible JavaScript and asset updates.
233
+ The upload will then target binaries built with that same runtime value.
117
234
 
118
- App Store and Play Store releases are slow and heavyweight.
235
+ When native code or native configuration changes, bump the affected platform's
236
+ literal and build a new binary before uploading updates for that runtime. For
237
+ example, an iOS-only native change should bump `runtimeVersion.ios`; Android can keep
238
+ its existing value. This makes the compatibility boundary explicit and prevents an
239
+ update from reaching a binary that cannot run it.
119
240
 
120
- BundleDrop gives you instant updates with full control without waiting for review.
241
+ ## Upload an Update
121
242
 
122
- ---
243
+ With the default literal runtime configuration, Expo uploads resolve the app version
244
+ through the Expo project and the runtime through `bundle.drop.config.js`. They do not
245
+ need `--version`, `--plist-file`, or Gradle-path options:
246
+
247
+ ```bash
248
+ npx bundle-drop upload ios --channel develop
249
+ npx bundle-drop upload android --channel develop
250
+ ```
251
+
252
+ Bare React Native uploads specify or resolve the app version explicitly:
253
+
254
+ ```bash
255
+ npx bundle-drop upload android --version 1.2.3 --channel develop
256
+ npx bundle-drop upload ios --plist-file ios/Info.plist --channel develop
257
+ ```
258
+
259
+ Add `--sourcemap` to produce source maps for error tracking. In CI/CD, pass a
260
+ Personal Access Token with `--token <PAT>` instead of using an interactive login.
261
+
262
+ ## Update Policies
263
+
264
+ `policy` controls what happens after Bundle Drop hydrates its local state on startup:
265
+
266
+ | Policy | Behavior |
267
+ | --- | --- |
268
+ | `manual` | Check only when you call the APIs yourself. Default. |
269
+ | `immediate` | Download and apply a new bundle right away. |
270
+ | `on-next-launch` | Stage the update now, then apply it on the next cold launch. |
271
+
272
+ `on-next-launch` is a good default for most apps: users do not see a reload in the
273
+ middle of a session, and the update is ready for the next launch.
274
+
275
+ ## Driving Updates Manually
276
+
277
+ For custom update UI, use the `useBundleDrop()` hook. It subscribes to the singleton
278
+ runtime and exposes actions plus live state:
279
+
280
+ ```tsx
281
+ import { Button } from 'react-native';
282
+ import { useBundleDrop } from '@gfean/react-native-bundle-drop';
283
+
284
+ function UpdateBanner() {
285
+ const { checkLatest, downloadUpdate, applyUpdate, pendingApply, isBusy } =
286
+ useBundleDrop();
287
+
288
+ if (pendingApply) {
289
+ return <Button title="Restart to update" onPress={applyUpdate} />;
290
+ }
291
+
292
+ return (
293
+ <Button
294
+ title="Check for updates"
295
+ disabled={isBusy}
296
+ onPress={async () => {
297
+ await checkLatest();
298
+ await downloadUpdate();
299
+ }}
300
+ />
301
+ );
302
+ }
303
+ ```
304
+
305
+ The same actions are available as standalone functions (`checkForUpdate`,
306
+ `downloadUpdate`, `applyUpdate`, `setChannel`, `reportHealthy`, and others) for use
307
+ outside React.
123
308
 
124
309
  ## Targeted Rollouts
125
310
 
126
- Use user properties to target specific cohorts:
311
+ Attach user properties to target specific cohorts when you stage a release:
127
312
 
128
313
  ```ts
129
314
  import { setUserProperty } from '@gfean/react-native-bundle-drop';
@@ -133,31 +318,111 @@ await setUserProperty('age', 33);
133
318
  await setUserProperty('beta', true);
134
319
  ```
135
320
 
136
- User property values must be strings, finite numbers, or booleans. Keys are trimmed and must be
137
- non-empty, 128 characters or fewer, and cannot start with `$`, contain `.`, contain a null byte, or
138
- use reserved prototype names.
321
+ Property values must be strings, finite numbers, or booleans. Keys are trimmed and
322
+ must be non-empty, 128 characters or fewer, and cannot start with `$`, contain `.`,
323
+ contain a null byte, or use reserved prototype names.
139
324
 
140
- ---
325
+ ## Hybrid OTA Delivery
141
326
 
142
- ## Docs
327
+ Bundle Drop installs complete, immutable bundle folders, each identified by a
328
+ canonical `bundleHash` for the reconstructed file tree. Patch transport is a download
329
+ optimization: the SDK reconstructs the complete target folder, validates the
330
+ manifest, verifies file hashes and sizes, and only then promotes the bundle.
143
331
 
144
- Full documentation:
332
+ - The SDK supports `asset-only-v1` patch sets and advertises `xdelta3-vcdiff` when
333
+ native xdelta support passes its probe.
334
+ - If patch transport is unavailable or fails, the SDK falls back to the signed
335
+ full ZIP.
336
+ - Rollback remains a local pointer switch between verified bundle hashes.
145
337
 
146
- - Website: [bundledrop.app](https://bundledrop.app)
147
- - Docs: [bundledrop.app/docs](https://bundledrop.app/docs)
148
- - Dashboard: [developer.bundledrop.app](https://developer.bundledrop.app)
338
+ The production manifest contract is `manifestVersion: 1`. `jsBundleHash` is retained
339
+ as metadata only.
149
340
 
150
- ---
341
+ ## Observability
151
342
 
152
- ## Notes
343
+ Every bundle has a unique hash, and `bundle-drop upload --sourcemap` produces source
344
+ maps so stack traces remain attributable across updates. Use
345
+ `getObservabilityContext()` to tag error reports with the running bundle:
153
346
 
154
- - Requires a BundleDrop backend and project setup
155
- - Supports React Native on iOS and Android
156
- - Requires iOS 13.0 or newer
157
- - Native package changes require rebuilding the host app; `nativeVersion` tracks that boundary
158
- - Best suited for bare React Native apps
347
+ ```ts
348
+ import { getObservabilityContext } from '@gfean/react-native-bundle-drop';
159
349
 
160
- ---
350
+ const context = await getObservabilityContext();
351
+ ```
352
+
353
+ This works with Sentry, Bugsnag, Datadog, and other error trackers. See the
354
+ [observability guide](https://bundledrop.app/docs/observability). Apps on
355
+ `@sentry/react-native` 7.8.x that combine Sentry's Metro wrapper with Hermes should
356
+ follow the guide's
357
+ [Sentry/Hermes OTA setup](https://bundledrop.app/docs/observability#sentry-and-hermes-ota-builds)
358
+ to keep content-derived Debug IDs from inflating binary patches.
359
+
360
+ ## API Reference
361
+
362
+ Import the runtime API from `@gfean/react-native-bundle-drop`.
363
+
364
+ **Runtime controller**
365
+
366
+ | Export | Description |
367
+ | --- | --- |
368
+ | `BundleDrop.init(options)` | Initialize the runtime for the app process. |
369
+ | `BundleDrop.setChannel(name)` / `setChannel` | Change the active channel for singleton actions. |
370
+ | `BundleDrop.getChannelName()` / `getChannelName` | Read the active channel. |
371
+ | `BundleDrop.reportHealthy()` / `reportHealthy` | Mark the running OTA candidate healthy for this device. |
372
+
373
+ **`BundleDrop.init(options)`**
374
+
375
+ | Option | Type | Default | Description |
376
+ | --- | --- | --- | --- |
377
+ | `environment` | `string` | Required | App environment shown in analytics, such as `production`, `staging`, or `development`. |
378
+ | `enabled` | `boolean` | `true` | When `false`, the SDK stays configured but does not check, download, or apply. |
379
+ | `channelName` | `string` | Config `defaultChannel` (`develop`) | Initial OTA channel for this process. |
380
+ | `policy` | `'manual' \| 'immediate' \| 'on-next-launch'` | `'manual'` | Startup behavior after hydration. |
381
+ | `checkOnly` | `boolean` | `false` | Startup resolves updates without downloading or applying them. |
382
+ | `onStatusUpdate` | `(status: string) => void` | — | Listener for human-readable status messages. |
383
+
384
+ **Update actions** — `checkForUpdate`, `downloadUpdate`, `installBundle`,
385
+ `applyUpdate`, `getUpdateState`, `getInstalledBundleInfo`, `getAvailableBundles`,
386
+ `getAvailableChannels`.
387
+
388
+ **React** — `useBundleDrop()` returns live state (`status`, `isEnabled`, `isBusy`,
389
+ `channelName`, `installedInfo`, `pendingApply`, `hasBundle`, `availableChannels`)
390
+ plus update actions.
391
+
392
+ **User properties** — `setUserProperty`, `removeUserProperty`, `getUserProperties`,
393
+ `getCurrentUserProperties`, `resetUserProperties`.
394
+
395
+ **Errors** — `BundleDropError`, `isBundleDropError`.
396
+
397
+ **Metro** — import `withBundleDropExpo` from
398
+ `@gfean/react-native-bundle-drop/metro` when configuring Expo Metro manually.
399
+
400
+ **CLI** (`npx bundle-drop <command>`) — `login`, `logout`, `whoami`, `init`,
401
+ `doctor`, `eas-receipt <ios|android>`, and `upload <ios|android>`.
402
+
403
+ ## Good to Know
404
+
405
+ - **OTA covers JavaScript and assets, not native code.** Native modules, native
406
+ dependency upgrades, permissions, native configuration, and React Native upgrades
407
+ require a new store binary.
408
+ - **Follow store policies.** Use OTA delivery for changes that remain within Apple
409
+ and Google requirements and the purpose of the reviewed app.
410
+ - **Compatibility checks are deliberate.** A device does not receive an update
411
+ built for a different app or runtime version.
412
+ - **Release builds run installed OTAs.** Expo Go, Debug builds, and development
413
+ clients continue to use their development JavaScript source.
414
+ - **Bundle Drop complements crash reporting.** It provides release identity and
415
+ source-map support; it does not replace an error tracker.
416
+
417
+ ## Docs and Links
418
+
419
+ - Website: [bundledrop.app](https://bundledrop.app)
420
+ - Docs: [bundledrop.app/docs](https://bundledrop.app/docs)
421
+ - Dashboard: [developer.bundledrop.app](https://developer.bundledrop.app)
422
+ - Migrating from CodePush: [bundledrop.app/codepush-alternative](https://bundledrop.app/codepush-alternative)
423
+ - Issues: [github.com/GFean/react-native-bundle-drop/issues](https://github.com/GFean/react-native-bundle-drop/issues)
424
+ - Security: [SECURITY.md](SECURITY.md)
425
+ - Contributing: [CONTRIBUTING.md](CONTRIBUTING.md)
161
426
 
162
427
  ## License
163
428
 
@@ -3,6 +3,7 @@ package com.bundledrop
3
3
  import android.content.Context
4
4
  import android.util.Log
5
5
  import java.io.File
6
+ import org.json.JSONObject
6
7
 
7
8
  /**
8
9
  * Resolves the on-disk OTA JS bundle path (no React / bridge types).
@@ -12,8 +13,22 @@ import java.io.File
12
13
  */
13
14
  object BundleDropNativePaths {
14
15
  private const val KEY_BINARY_VERSION = "binary_version"
16
+ private const val BUILD_IDENTITY_ASSET = "bundle-drop/build-identity.json"
15
17
 
16
- private fun getBinaryVersionKey(context: Context): String {
18
+ internal fun binaryVersionKey(
19
+ versionName: String,
20
+ versionCode: Long,
21
+ runtimeVersion: String?,
22
+ ): String {
23
+ val binaryVersion = "$versionName-$versionCode"
24
+ return if (runtimeVersion?.trim().isNullOrEmpty()) {
25
+ binaryVersion
26
+ } else {
27
+ "runtime:$runtimeVersion|binary:$binaryVersion"
28
+ }
29
+ }
30
+
31
+ private fun getBinaryVersionKey(context: Context, runtimeVersion: String?): String {
17
32
  val pInfo = context.packageManager.getPackageInfo(context.packageName, 0)
18
33
  val versionName = pInfo.versionName ?: "unknown"
19
34
  @Suppress("DEPRECATION")
@@ -22,7 +37,19 @@ object BundleDropNativePaths {
22
37
  } else {
23
38
  pInfo.versionCode.toLong()
24
39
  }
25
- return "$versionName-$versionCode"
40
+ return binaryVersionKey(versionName, versionCode, runtimeVersion)
41
+ }
42
+
43
+ internal fun readEmbeddedRuntimeVersion(context: Context): String? {
44
+ return try {
45
+ context.assets.open(BUILD_IDENTITY_ASSET).bufferedReader().use { reader ->
46
+ JSONObject(reader.readText())
47
+ .optString("runtimeVersion", "")
48
+ .takeIf { it.trim().isNotEmpty() }
49
+ }
50
+ } catch (_: Exception) {
51
+ null
52
+ }
26
53
  }
27
54
 
28
55
  private fun getStoredBinaryVersion(context: Context): String? {
@@ -38,12 +65,15 @@ object BundleDropNativePaths {
38
65
  @JvmStatic
39
66
  fun getDownloadedBundlePath(context: Context): String? {
40
67
  if (!BundleDropOtaPrefs.isOtaEnabled(context)) return null
68
+ return getDownloadedBundlePath(context, readEmbeddedRuntimeVersion(context))
69
+ }
41
70
 
71
+ internal fun getDownloadedBundlePath(context: Context, runtimeVersion: String?): String? {
42
72
  val bundleDropRoot = File(context.filesDir, "bundle-drop")
43
73
  val result = BundleDropOtaResolver.resolve(
44
74
  bundleDropRoot = bundleDropRoot,
45
75
  filesDir = context.filesDir,
46
- currentBinaryVersion = getBinaryVersionKey(context),
76
+ currentBinaryVersion = getBinaryVersionKey(context, runtimeVersion),
47
77
  storedBinaryVersion = getStoredBinaryVersion(context),
48
78
  )
49
79
 
package/app.plugin.js ADDED
@@ -0,0 +1,3 @@
1
+ 'use strict';
2
+
3
+ module.exports = require('./plugin');