@gfean/react-native-bundle-drop 0.2.2 → 0.3.3

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 (37) hide show
  1. package/BundleDrop.podspec +2 -1
  2. package/LICENSE +15 -0
  3. package/README.md +122 -238
  4. package/lib/CLI/cli.d.ts +2 -1
  5. package/lib/CLI/cli.js +154 -131
  6. package/lib/CLI/scripts/init-config.js +12 -5
  7. package/lib/CLI/scripts/init-native-config.d.ts +16 -0
  8. package/lib/CLI/scripts/init-native-config.js +28 -9
  9. package/lib/CLI/scripts/login-cli.d.ts +71 -0
  10. package/lib/CLI/scripts/login-cli.js +24 -13
  11. package/lib/CLI/scripts/post-init.js +9 -3
  12. package/lib/CLI/scripts/upload-cli.js +14 -7
  13. package/lib/api/types.d.ts +29 -0
  14. package/lib/index.d.ts +16 -4
  15. package/lib/index.js +25 -15
  16. package/lib/manager/downloadAndInstall.d.ts +2 -0
  17. package/lib/manager/reporting.js +3 -0
  18. package/lib/manager/updateCheck.d.ts +13 -0
  19. package/lib/manager/updateCheck.js +6 -0
  20. package/lib/manager/updateState.d.ts +2 -0
  21. package/lib/manager/updateState.js +10 -4
  22. package/lib/runtime/initState.d.ts +48 -0
  23. package/lib/runtime/initState.js +131 -0
  24. package/lib/runtime/service.d.ts +111 -0
  25. package/lib/runtime/service.js +537 -0
  26. package/lib/scripts/bundle.d.ts +13 -1
  27. package/lib/scripts/bundle.js +126 -115
  28. package/lib/scripts/download-bundle.d.ts +4 -1
  29. package/lib/scripts/download-bundle.js +41 -33
  30. package/lib/scripts/upload-bundle.d.ts +7 -1
  31. package/lib/scripts/upload-bundle.js +183 -175
  32. package/lib/useBundleDrop.d.ts +19 -9
  33. package/lib/useBundleDrop.js +26 -172
  34. package/package.json +59 -8
  35. package/CLIENT_README.md +0 -381
  36. package/lib/manager/initUpdateManager.d.ts +0 -10
  37. package/lib/manager/initUpdateManager.js +0 -137
@@ -1,10 +1,11 @@
1
1
  require "json"
2
2
 
3
3
  package = JSON.parse(File.read(File.join(__dir__, "package.json")))
4
+ native_version = package["nativeVersion"] || package["version"]
4
5
 
5
6
  Pod::Spec.new do |s|
6
7
  s.name = "BundleDrop"
7
- s.version = package["version"]
8
+ s.version = native_version
8
9
  s.summary = package["description"]
9
10
  s.homepage = package["homepage"]
10
11
  s.license = package["license"]
package/LICENSE ADDED
@@ -0,0 +1,15 @@
1
+ ISC License
2
+
3
+ Copyright (c) 2026 GFean
4
+
5
+ Permission to use, copy, modify, and/or distribute this software for any
6
+ purpose with or without fee is hereby granted, provided that the above
7
+ copyright notice and this permission notice appear in all copies.
8
+
9
+ THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
10
+ REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11
+ AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
12
+ INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13
+ LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
14
+ OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15
+ PERFORMANCE OF THIS SOFTWARE.
package/README.md CHANGED
@@ -1,255 +1,139 @@
1
- # React Native Bundle Drop (OTA) — Module Guide
1
+ # BundleDrop
2
2
 
3
- This package powers OTA bundle download/upload and asset resolution for React Native.
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
+ [![license](https://img.shields.io/badge/license-ISC-84cc16)](#license)
5
+ [![website](https://img.shields.io/badge/website-bundledrop.app-2563eb)](https://bundledrop.app)
6
+ [![docs](https://img.shields.io/badge/docs-bundledrop.app%2Fdocs-0f766e)](https://bundledrop.app/docs)
7
+ [![dashboard](https://img.shields.io/badge/dashboard-developer.bundledrop.app-111827)](https://developer.bundledrop.app)
8
+
9
+ Deploy React Native updates instantly — skip App Store and Play Store delays entirely.
10
+
11
+ Drop-in OTA solution for bare React Native apps.
12
+
13
+ [Website](https://bundledrop.app) • [Docs](https://bundledrop.app/docs) • [Dashboard](https://developer.bundledrop.app)
14
+
15
+ ---
16
+
17
+ ## Why BundleDrop?
18
+
19
+ Shipping a small fix should not require a full mobile release.
20
+
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
27
+
28
+ Built for production React Native apps.
29
+
30
+ ---
31
+
32
+ ## What You Can Do
33
+
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
39
+
40
+ ---
41
+
42
+ ## Installation
4
43
 
5
- ## Install
6
44
  ```bash
7
- yarn add @gfean/react-native-bundle-drop
8
- cd ios && pod install && cd ..
45
+ npm install @gfean/react-native-bundle-drop
9
46
  ```
10
47
 
11
- ### Metro config (to resolve bundle.drop.config.js from node_modules)
12
- If Metro cannot resolve `bundle.drop.config.js` from within `node_modules`, add an alias in `metro.config.js`:
13
- ```js
14
- // metro.config.js
15
- const path = require('path');
16
-
17
- module.exports = {
18
- resolver: {
19
- extraNodeModules: {
20
- // Allows packages to do: require('bundle-drop-config')
21
- 'bundle-drop-config': path.resolve(__dirname, 'bundle.drop.config.js'),
22
- },
23
- },
24
- };
48
+ ```bash
49
+ cd ios && pod install
25
50
  ```
26
51
 
27
- ## Prerequisites
28
- - `bundle.drop.config.js` in your app root:
29
- ```js
30
- module.exports = {
31
- serverUrl: 'http://localhost:4000', // or prod URL
32
- org: { slug: 'your-org-slug' },
33
- project: {
34
- name: 'Your App Name',
35
- slug: 'your-app-slug',
36
- apiKey: 'optional-api-key', // project-scoped; auto-filled by CLI init/login
37
- },
38
- debugLocal: true, // optional: force localhost (10.0.2.2 on Android, localhost on iOS)
39
- };
40
- ```
41
- - Login token stored at `~/.bundle-drop/auth.json` (use CLI `bundle-drop login`).
42
- - The CLI will fetch a project-scoped `apiKey` from `GET /projects/:projectSlug/credentials` using your JWT and write it into `bundle.drop.config.js`. If you have multiple projects, the CLI prompts you to select the project before fetching credentials.
43
-
44
- ## Runtime APIs (app code)
45
- - `checkForUpdate(channelName?, onStatusUpdate?)`: resolve-only metadata check (no download). Uses `POST /projects/:projectSlug/ota/resolve` and can return `NOOP`, `INSTALL`, or `ROLLBACK` (plus `NO_COMPATIBLE_BUNDLE` details).
46
- - `downloadUpdate(options?, onStatusUpdate?)`: resolves (unless `resolvedTarget` is provided), downloads, and stages the update (sets `pendingApply: true`). Returns `{ status: 'staged' | 'upToDate' | 'rollback' | 'incompatible' }`.
47
- - `applyUpdate(onStatusUpdate?)`: apply a staged update now (restarts the RN bridge).
48
- - `getUpdateState()`: returns `{ hasBundle, info, pendingApply }` from local metadata.
49
- - `initUpdateManager({ channelName, policy, onStatusUpdate, checkOnly })`: startup helper
50
- - `policy: 'manual' | 'immediate' | 'on-next-launch'`
51
- - `immediate`: download and stage, then apply now (reload). If a staged update is pending, applies it immediately.
52
- - `on-next-launch`: download and stage; app will pick it up on the next launch (pending flag remains until applied).
53
- - `manual`: no auto download/apply (resolve still runs for status and rollback decisions).
54
- - On launch it reconciles pending state, runs rollback guardrails, auto-commits the active bundle, then resolves once. If `ROLLBACK` is returned it switches to `previous.json` (or native fallback) and restarts.
55
- - `useBundleDrop` hook (optional helper): returns status, busy flag, installed info, pending state, and actions (`checkLatest`, `downloadUpdate`, `applyUpdate`, `fetchAvailableChannels`). Action calls return structured results plus the status string they set.
56
- - User property APIs (for targeted rollout):
57
- - `setUserProperty(value: string)`: add a user property (trimmed, de-duplicated).
58
- - `setUserPropery(value: string)`: backward-compatible alias of `setUserProperty`.
59
- - `getUserProperties()` and `getCurrentUserProperties()`: read all saved properties.
60
- - `removeUserProperty(value: string)`: remove one property.
61
- - `resetUserProperties()`: clear all properties.
62
-
63
- Android extras:
64
- - Asset resolver patches (`injectBundleDropImageResolver`, `patchImageRenderToForceResolve`) are applied on module load so images referenced directly still resolve after OTA.
65
- - Manifest is built at bundle time and merged with a runtime manifest built during unzip to cover filename-only lookups.
66
-
67
- ## Config loading
68
- - `src/loadConfig.ts` loads `bundle.drop.config.js` (fixed relative path) and honors `debugLocal` to force localhost.
69
-
70
- ## Server API (Public)
71
- All endpoints are project-scoped and require `x-api-key` (project download API key).
72
-
73
- ### `POST /projects/:projectSlug/ota/resolve`
74
- Request body:
75
- ```json
76
- {
77
- "channelName": "General",
78
- "platform": "ios|android",
79
- "runtimeVersion": "3.0.0",
80
- "currentHash": "abc123",
81
- "currentUserProperties": ["QA Analyst", "Beta Tester"],
82
- "previousHash": "prev456",
83
- "currentBundleVersion": 12,
84
- "installId": "install-id-string"
85
- }
86
- ```
87
- Notes:
88
- - `installId` is generated once per install and stored at `bundle-drop/install-id.txt` (under the platform-specific `bundle-drop` root).
89
- - `previousHash` is read from `previous.json` when available.
90
- - `currentUserProperties` is read from local `bundle-drop/user-properties.json` and sent automatically on each resolve.
91
-
92
- Response shapes:
93
- ```json
94
- { "action": "NOOP", "reason": "UP_TO_DATE" }
95
- ```
96
- ```json
97
- {
98
- "action": "NOOP",
99
- "reason": "NO_COMPATIBLE_BUNDLE",
100
- "requestedRuntimeVersion": "3.0.0",
101
- "latestRuntimeVersionOnChannel": "3.1.0"
102
- }
103
- ```
104
- ```json
105
- {
106
- "action": "INSTALL",
107
- "target": {
108
- "hash": "def789",
109
- "downloadUrl": "https://signed-url",
110
- "bundleVersion": 13,
111
- "version": "optional",
112
- "runtimeVersion": "optional"
113
- }
114
- }
115
- ```
116
- ```json
117
- { "action": "ROLLBACK", "reason": "CURRENT_REVOKED_NO_SAFE_TARGET" }
118
- ```
119
- Notes:
120
- - `NOOP` reasons: `UP_TO_DATE`, `ROLLOUT_PAUSED`, `ROLLOUT_NOT_ELIGIBLE`, `NO_PUBLISHED_BUNDLE`, `NO_COMPATIBLE_BUNDLE`.
121
- - `ROLLBACK` reasons are server-defined (for example: `CURRENT_REVOKED_NO_SAFE_TARGET`, `CURRENT_REVOKED_NO_COMPATIBLE_TARGET`).
122
- Client behavior:
123
- - `NOOP`: do nothing.
124
- - `INSTALL`: download `target.downloadUrl`, stage it, then apply per policy.
125
- - `ROLLBACK`: switch to `previous.json` if present; otherwise clear `current.json` and fall back to the native bundle (no re-download).
126
-
127
- ### `POST /projects/:projectSlug/bundle/:hash/installed`
128
- Called once the staged bundle is active (after apply on launch). Used for telemetry.
129
- Payload fields:
130
- - `channelName`
131
- - `platform`
132
- - `installId` (persistent per-install id stored at `bundle-drop/install-id.txt`)
133
- - `runtimeVersion`
134
-
135
- ### `GET /projects/:projectSlug/channels/public`
136
- Returns the list of public channel names.
137
-
138
- ## Rollback behavior (default)
139
- - Bundles are stored by hash under the platform `bundle-drop` root and activated via `current.json`.
140
- - The previous active bundle is retained in `previous.json` for rollback.
141
- - A small `state.json` tracks candidate activation, crash window, and commit status.
142
- - The module auto-commits the active bundle once JS has started (via `initUpdateManager`/`useBundleDrop`).
143
- - Server-triggered rollback switches the pointer; if no previous OTA bundle exists, it falls back to the native bundle by clearing `current.json`.
144
-
145
- Optional rollback policy (tuning only):
146
- ```js
147
- rollback: {
148
- maxCrashCount: 2,
149
- crashWindowSec: 300,
150
- commitTimeoutSec: 300,
151
- }
152
- ```
52
+ ---
53
+
54
+ ## Quick Start
55
+
56
+ ### 1. Connect your project
153
57
 
154
- ## Bundling & Uploading (CLI)
155
- - Login once (interactive, stores JWT locally):
156
- ```bash
157
- npx bundle-drop login
158
- ```
159
- - If you need to (re)generate config and fetch the project-scoped API key:
160
- ```bash
161
- npx bundle-drop init
162
- npx bundle-drop init --token bdp_pat_xxx # alternative: use a PAT instead of login
163
- ```
164
- - Upload (builds, zips, uploads, cleans up):
165
- ```bash
166
- npx bundle-drop upload android --version 1.2.3 --channel General
167
- npx bundle-drop upload ios --plist-file ios/Info.plist --channel General
168
- ```
169
- Flags:
170
- - `--version` (ios/android) or `--plist-file` (iOS) or `--buildgradle-path` (Android) to derive version.
171
- - `--release-notes "<text>"` optional release notes (max 2000 chars).
172
- - `--token <pat>` use a Personal Access Token instead of `bundle-drop login`. Ideal for CI/CD.
173
- - `--author <name>` override the author name stored with the bundle (defaults to uploading user's name).
174
- - `--runtimeVersion <v>` override runtimeVersion from metadata/config.
175
-
176
- Requirements:
177
- - `bundle.drop.config.js` with `serverUrl`, `org.slug`, `project.slug`.
178
- - `project.apiKey` is used by the client for public endpoints (channel listing + OTA resolve).
179
- - Authentication via one of: `--token` flag (PAT), or `~/.bundle-drop/auth.json` from `bundle-drop login`.
180
-
181
- ### CI/CD example
182
58
  ```bash
183
- npx bundle-drop upload android \
184
- --version 1.2.3 \
185
- --channel General \
186
- --token $BUNDLE_DROP_PAT \
187
- --author "CI Pipeline"
59
+ npx bundle-drop login
60
+ npx bundle-drop init
188
61
  ```
189
62
 
190
- ## Typical usage
63
+ ### 2. Bootstrap BundleDrop in your app
64
+
191
65
  ```ts
192
- // App.tsx startup (optional auto behavior)
193
- useEffect(() => {
194
- initUpdateManager({
195
- policy: __DEV__ ? 'manual' : 'on-next-launch', // or 'immediate'
196
- channelName: 'General',
197
- onStatusUpdate: msg => console.log('[OTA]', msg),
198
- });
199
- }, []);
200
-
201
- // Manual UI (hook)
202
- const {
203
- status,
204
- isBusy,
205
- installedInfo,
206
- pendingApply,
207
- checkLatest,
208
- downloadUpdate,
209
- applyUpdate,
210
- } = useBundleDrop({ channelName: 'General' });
211
-
212
- // downloadUpdate() will stage the bundle (applies on next launch or when you call applyUpdate()).
66
+ import { BundleDrop } from '@gfean/react-native-bundle-drop';
67
+
68
+ BundleDrop.init({
69
+ enabled: !__DEV__,
70
+ environment: __DEV__ ? 'STAG' : 'PROD',
71
+ policy: 'on-next-launch',
72
+ channelName: 'General',
73
+ });
74
+ ```
75
+
76
+ ### 3. Ship an update
77
+
78
+ ```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
213
81
  ```
214
82
 
215
- ## Targeted rollout properties
83
+ Use `--token` in CI/CD pipelines.
84
+
85
+ ---
86
+
87
+ ## Update Policies
88
+
89
+ Choose how updates are applied:
90
+
91
+ - `manual`: check only, no automatic apply
92
+ - `immediate`: download and apply right away
93
+ - `on-next-launch`: stage now, apply on next launch
94
+
95
+ `on-next-launch` is the safest default for most apps.
96
+
97
+ ---
98
+
99
+ ## Why Not App Store Updates?
100
+
101
+ App Store and Play Store releases are slow and heavyweight.
102
+
103
+ BundleDrop gives you instant updates with full control without waiting for review.
104
+
105
+ ---
106
+
107
+ ## Targeted Rollouts
108
+
109
+ Use user properties to target specific cohorts:
110
+
216
111
  ```ts
217
- import {
218
- setUserProperty,
219
- getUserProperties,
220
- removeUserProperty,
221
- resetUserProperties,
222
- } from '@gfean/react-native-bundle-drop';
223
-
224
- await setUserProperty('QA Analyst');
225
- await setUserProperty('Beta Tester');
226
- await setUserProperty('QA Analyst'); // duplicate ignored
227
-
228
- const props = await getUserProperties(); // ['QA Analyst', 'Beta Tester']
229
- await removeUserProperty('Beta Tester');
230
- await resetUserProperties();
112
+ import { setUserProperty } from '@gfean/react-native-bundle-drop';
113
+
114
+ await setUserProperty('beta');
231
115
  ```
232
116
 
233
- ## CLI (bin)
234
- - `modules/react-native-bundle-drop/src/CLI/cli.ts` provides:
235
- - `bundle-drop login|logout|whoami`
236
- - `bundle-drop init [--token <pat>]`
237
- - `bundle-drop upload <platform> --version <ver> --channel <name> [--plist-file <path>] [--runtimeVersion <v>] [--release-notes "<text>"] [--token <pat>] [--author <name>]`
238
- - Auth via `--token` (PAT) or `~/.bundle-drop/auth.json` (from `bundle-drop login`).
239
-
240
- ## Android localhost note
241
- - When `debugLocal` is true (or env is set), Android uses `http://10.0.2.2:4000`; iOS uses `http://localhost:4000`.
242
-
243
- ## Troubleshooting
244
- - If bundling fails with `EMFILE`, raise file descriptor limit (`ulimit -n 8192`) and retry.
245
- - Ensure `bundle.drop.config.js` has `serverUrl`, `org.slug`, and `project.slug`; otherwise the module falls back to localhost defaults.
246
-
247
- ## Maintainer notes (internal structure)
248
- - `src/index.tsx` is a thin barrel for public exports.
249
- - Early side-effects/config live in `src/bootstrap.ts` (loads config, detects platform, patches Android images).
250
- - File system helpers: `src/fs/*` (atomic writes, bundle pointers).
251
- - Rollback/state helpers: `src/manager/rollbackState.ts`.
252
- - Native accessors: `src/native/bundleDropNative.ts`.
253
- - Install flow: `src/install/installFromZip.ts`.
254
- - API client layer: `src/api/*` (axios client + typed endpoints).
255
- - Update managers: `src/manager/*` (`updateCheck`, `downloadAndInstall`, `updateState`, `reporting`, `initUpdateManager`).
117
+ ---
118
+
119
+ ## Docs
120
+
121
+ Full documentation:
122
+
123
+ - Website: [bundledrop.app](https://bundledrop.app)
124
+ - Docs: [bundledrop.app/docs](https://bundledrop.app/docs)
125
+ - Dashboard: [developer.bundledrop.app](https://developer.bundledrop.app)
126
+
127
+ ---
128
+
129
+ ## Notes
130
+
131
+ - Requires a BundleDrop backend and project setup
132
+ - Supports React Native on iOS and Android
133
+ - Best suited for bare React Native apps
134
+
135
+ ---
136
+
137
+ ## License
138
+
139
+ ISC
package/lib/CLI/cli.d.ts CHANGED
@@ -1,2 +1,3 @@
1
1
  #!/usr/bin/env node
2
- export {};
2
+ import { Command } from 'commander';
3
+ export declare const buildProgram: () => Command;