pulse-updates 1.0.0

package/README.md

@@ -0,0 +1,333 @@
+# Pulse Updates
+
+Lightweight OTA (Over-The-Air) updates for React Native apps. A simpler alternative to expo-updates with full support for React Native's New Architecture (Fabric/Bridgeless).
+
+## Features
+
+- Full support for React Native New Architecture (Bridgeless mode)
+- Automatic asset resolution with embedded fallback
+- Hermes bytecode compilation for faster startup
+- Incremental updates (only changed assets are downloaded)
+- Rollback protection with health checks
+- Channel-based deployments (production, staging, etc.)
+- Compatible with expo-asset resolution
+
+## Installation
+
+```bash
+npm install pulse-updates
+# or
+yarn add pulse-updates
+```
+
+### iOS Setup
+
+Add to your `Podfile`:
+
+```ruby
+pod 'pulse-updates', :path => '../node_modules/pulse-updates'
+```
+
+Then run:
+
+```bash
+cd ios && pod install
+```
+
+Add these keys to your `Info.plist`:
+
+```xml
+<key>PulseUpdatesEnabled</key>
+<true/>
+<key>PulseUpdatesURL</key>
+<string>https://your-update-server.com</string>
+<key>PulseUpdatesRuntimeVersion</key>
+<string>$(MARKETING_VERSION)</string>
+<key>PulseUpdatesCheckOnLaunch</key>
+<string>ALWAYS</string>
+```
+
+### Android Setup
+
+Add to your `android/app/build.gradle`:
+
+```gradle
+dependencies {
+    implementation project(':pulse-updates')
+}
+```
+
+Add metadata to `AndroidManifest.xml` inside `<application>`:
+
+```xml
+<meta-data android:name="PulseUpdatesEnabled" android:value="true" />
+<meta-data android:name="PulseUpdatesURL" android:value="https://your-update-server.com" />
+<meta-data android:name="PulseUpdatesRuntimeVersion" android:value="@string/app_version" />
+<meta-data android:name="PulseUpdatesCheckOnLaunch" android:value="ALWAYS" />
+```
+
+#### New Architecture (Bridgeless) Setup
+
+For React Native 0.76+ with New Architecture enabled, update your `MainApplication.kt`:
+
+```kotlin
+import app.pulse.updates.PulseUpdatesModule
+import app.pulse.updates.PulseReactHostFactory
+
+class MainApplication : Application(), ReactApplication {
+
+    // Extract packages into a reusable method
+    private fun buildPackages(): List<ReactPackage> {
+        val packages = PackageList(this).packages.toMutableList()
+        // Add your custom packages here
+        return packages
+    }
+
+    override val reactNativeHost: ReactNativeHost =
+        object : DefaultReactNativeHost(this) {
+            override fun getPackages(): List<ReactPackage> = buildPackages()
+            override fun getJSMainModuleName(): String = "index"
+
+            // Use Pulse Updates bundle
+            override fun getJSBundleFile(): String? {
+                return PulseUpdatesModule.getBundleFile(applicationContext)?.absolutePath
+                    ?: super.getJSBundleFile()
+            }
+
+            override val isNewArchEnabled: Boolean = BuildConfig.IS_NEW_ARCHITECTURE_ENABLED
+            override val isHermesEnabled: Boolean = BuildConfig.IS_HERMES_ENABLED
+        }
+
+    // For New Architecture: use PulseReactHostFactory
+    override val reactHost: ReactHost
+        get() = PulseReactHostFactory.createReactHost(
+            applicationContext,
+            packages = buildPackages(),
+            jsMainModuleName = "index",
+            useDevSupport = BuildConfig.DEBUG
+        )
+}
+```
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `PulseUpdatesEnabled` | boolean | `true` | Enable/disable OTA updates |
+| `PulseUpdatesURL` | string | required | Your update server URL |
+| `PulseUpdatesRuntimeVersion` | string | app version | Version for update compatibility |
+| `PulseUpdatesCheckOnLaunch` | string | `ALWAYS` | When to check: `ALWAYS`, `WIFI_ONLY`, `NEVER` |
+| `PulseUpdatesChannel` | string | `production` | Update channel |
+| `PulseUpdatesLaunchWaitMs` | number | `0` | Wait time for update check on launch |
+
+## JavaScript API
+
+### Basic Usage
+
+```typescript
+import * as PulseUpdates from 'pulse-updates';
+import { initializeAssetResolver } from 'pulse-updates';
+
+// Initialize at app startup
+async function initUpdates() {
+  // Refresh state from native module
+  await PulseUpdates.refreshStateAsync();
+
+  // Initialize asset resolver for images
+  initializeAssetResolver(PulseUpdates.localAssets);
+
+  // Check current state
+  console.log('Update ID:', PulseUpdates.updateId);
+  console.log('Is embedded:', PulseUpdates.isEmbeddedLaunch);
+}
+
+// Check for updates
+async function checkUpdates() {
+  const result = await PulseUpdates.checkForUpdateAsync();
+
+  if (result.isAvailable) {
+    console.log('Update available:', result.manifest?.updateId);
+
+    // Download the update
+    const fetchResult = await PulseUpdates.fetchUpdateAsync();
+
+    if (fetchResult.isNew) {
+      // Reload to apply
+      await PulseUpdates.reloadAsync();
+    }
+  }
+}
+```
+
+### React Hook
+
+```typescript
+import { usePulseUpdates } from 'pulse-updates';
+
+function UpdateBanner() {
+  const {
+    isChecking,
+    isDownloading,
+    availableUpdate,
+    downloadedUpdate,
+    checkForUpdate,
+    downloadUpdate,
+    reload
+  } = usePulseUpdates();
+
+  if (downloadedUpdate) {
+    return (
+      <View>
+        <Text>Update ready!</Text>
+        <Button title="Restart" onPress={reload} />
+      </View>
+    );
+  }
+
+  if (availableUpdate) {
+    return (
+      <View>
+        <Text>Update available</Text>
+        <Button
+          title={isDownloading ? "Downloading..." : "Download"}
+          onPress={downloadUpdate}
+          disabled={isDownloading}
+        />
+      </View>
+    );
+  }
+
+  return null;
+}
+```
+
+### API Reference
+
+#### State Properties
+
+```typescript
+PulseUpdates.isEnabled        // boolean - Updates enabled
+PulseUpdates.updateId         // string | null - Current update ID
+PulseUpdates.runtimeVersion   // string | null - Runtime version
+PulseUpdates.channel          // string | null - Update channel
+PulseUpdates.isEmbeddedLaunch // boolean - Running embedded bundle
+PulseUpdates.manifest         // PulseManifest | null - Current manifest
+PulseUpdates.localAssets      // Record<string, string> | null - Local asset map
+```
+
+#### Methods
+
+```typescript
+// Refresh state from native
+await PulseUpdates.refreshStateAsync()
+
+// Check for available updates
+const result = await PulseUpdates.checkForUpdateAsync()
+// Returns: { isAvailable: boolean, manifest?: PulseManifest }
+
+// Download available update
+const result = await PulseUpdates.fetchUpdateAsync()
+// Returns: { isNew: boolean, manifest?: PulseManifest }
+
+// Reload app with new update
+await PulseUpdates.reloadAsync()
+
+// Mark app as successfully launched (for rollback protection)
+await PulseUpdates.markAppReady()
+
+// Report launch failure (triggers rollback)
+await PulseUpdates.reportLaunchFailure(reason: string)
+```
+
+## CLI Commands
+
+### Publishing Updates
+
+```bash
+# Publish an update
+npx pulse-updates publish --platform <ios|android> --build <number>
+
+# With all options
+npx pulse-updates publish \
+  --platform ios \
+  --build 42 \
+  --channel production \
+  --api-key your-api-key \
+  --api-url https://your-server.com \
+  --runtime-version 1.0.0 \
+  --message "Bug fixes and improvements"
+```
+
+### CLI Options
+
+| Option | Description |
+|--------|-------------|
+| `--platform` | Target platform: `ios` or `android` (required) |
+| `--build` | Build number for this update (required) |
+| `--channel` | Update channel (default: `production`) |
+| `--api-key` | Server API key (or set in `pulse.config.json`) |
+| `--api-url` | Server URL (auto-detected from native config) |
+| `--runtime-version` | Runtime version (auto-detected from native config) |
+| `--message` | Release notes |
+| `--skip-bundle` | Skip bundle creation (use existing) |
+
+### Configuration File
+
+Create `pulse.config.json` in your project root:
+
+```json
+{
+  "apiKey": "your-api-key",
+  "apiUrl": "https://your-server.com",
+  "channel": "production"
+}
+```
+
+## Server Requirements
+
+Pulse Updates requires a compatible server. The server must implement:
+
+- `POST /api/releases` - Create new release
+- `POST /api/assets/check` - Check which assets exist
+- `POST /api/assets/upload` - Upload assets
+- `POST /api/releases/:id/finalize` - Finalize release
+- `GET /api/manifest/:appId` - Get latest manifest
+
+## Embedded Manifest
+
+For offline-first support, generate an embedded manifest during your build:
+
+```bash
+node node_modules/pulse-updates/scripts/generate-embedded-manifest.mjs \
+  --bundle path/to/index.bundle \
+  --assets path/to/assets \
+  --out path/to/output \
+  --platform ios \
+  --runtime-version 1.0.0
+```
+
+## Troubleshooting
+
+### Images not loading after update
+
+Ensure you initialize the asset resolver at app startup:
+
+```typescript
+import { initializeAssetResolver } from 'pulse-updates';
+import * as PulseUpdates from 'pulse-updates';
+
+await PulseUpdates.refreshStateAsync();
+initializeAssetResolver(PulseUpdates.localAssets);
+```
+
+### Update not applying on reload
+
+For New Architecture apps, ensure you're using `PulseReactHostFactory` in your `MainApplication.kt`.
+
+### Debug Logging
+
+Set `PULSE_DEBUG=true` environment variable to enable verbose logging in native code.
+
+## License
+
+MIT

package/android/build/.transforms/051997ae5715069c07acae848c6dd9c5/results.bin

@@ -0,0 +1 @@
+o/bundleLibRuntimeToDirRelease

package/android/build/.transforms/1a2af57545c1657f87f3de30891a3470/results.bin

@@ -0,0 +1 @@
+o/classes

package/android/build/generated/source/buildConfig/debug/app/pulse/updates/BuildConfig.java

@@ -0,0 +1,10 @@
+/**
+ * Automatically generated file. DO NOT MODIFY
+ */
+package app.pulse.updates;
+
+public final class BuildConfig {
+  public static final boolean DEBUG = Boolean.parseBoolean("true");
+  public static final String LIBRARY_PACKAGE_NAME = "app.pulse.updates";
+  public static final String BUILD_TYPE = "debug";
+}

package/android/build/generated/source/buildConfig/release/app/pulse/updates/BuildConfig.java

@@ -0,0 +1,10 @@
+/**
+ * Automatically generated file. DO NOT MODIFY
+ */
+package app.pulse.updates;
+
+public final class BuildConfig {
+  public static final boolean DEBUG = false;
+  public static final String LIBRARY_PACKAGE_NAME = "app.pulse.updates";
+  public static final String BUILD_TYPE = "release";
+}

package/android/build/intermediates/aapt_friendly_merged_manifests/debug/processDebugManifest/aapt/AndroidManifest.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    package="app.pulse.updates" >
+
+    <uses-sdk android:minSdkVersion="24" />
+
+    <uses-permission android:name="android.permission.INTERNET" />
+
+</manifest>

package/android/build/intermediates/aapt_friendly_merged_manifests/debug/processDebugManifest/aapt/output-metadata.json

@@ -0,0 +1,18 @@
+{
+  "version": 3,
+  "artifactType": {
+    "type": "AAPT_FRIENDLY_MERGED_MANIFESTS",
+    "kind": "Directory"
+  },
+  "applicationId": "app.pulse.updates",
+  "variantName": "debug",
+  "elements": [
+    {
+      "type": "SINGLE",
+      "filters": [],
+      "attributes": [],
+      "outputFile": "AndroidManifest.xml"
+    }
+  ],
+  "elementType": "File"
+}

package/android/build/intermediates/aapt_friendly_merged_manifests/release/processReleaseManifest/aapt/AndroidManifest.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    package="app.pulse.updates" >
+
+    <uses-sdk android:minSdkVersion="24" />
+
+    <uses-permission android:name="android.permission.INTERNET" />
+
+</manifest>

package/android/build/intermediates/aapt_friendly_merged_manifests/release/processReleaseManifest/aapt/output-metadata.json

@@ -0,0 +1,18 @@
+{
+  "version": 3,
+  "artifactType": {
+    "type": "AAPT_FRIENDLY_MERGED_MANIFESTS",
+    "kind": "Directory"
+  },
+  "applicationId": "app.pulse.updates",
+  "variantName": "debug",
+  "elements": [
+    {
+      "type": "SINGLE",
+      "filters": [],
+      "attributes": [],
+      "outputFile": "AndroidManifest.xml"
+    }
+  ],
+  "elementType": "File"
+}

package/android/build/intermediates/aar_metadata/debug/writeDebugAarMetadata/aar-metadata.properties

@@ -0,0 +1,6 @@
+aarFormatVersion=1.0
+aarMetadataVersion=1.0
+minCompileSdk=1
+minCompileSdkExtension=0
+minAndroidGradlePluginVersion=1.0.0
+coreLibraryDesugaringEnabled=false

package/android/build/intermediates/aar_metadata/release/writeReleaseAarMetadata/aar-metadata.properties

@@ -0,0 +1,6 @@
+aarFormatVersion=1.0
+aarMetadataVersion=1.0
+minCompileSdk=1
+minCompileSdkExtension=0
+minAndroidGradlePluginVersion=1.0.0
+coreLibraryDesugaringEnabled=false

package/android/build/intermediates/annotation_processor_list/debug/javaPreCompileDebug/annotationProcessors.json

@@ -0,0 +1 @@
+{}

package/android/build/intermediates/annotation_processor_list/release/javaPreCompileRelease/annotationProcessors.json

@@ -0,0 +1 @@
+{}

package/android/build/intermediates/incremental/debug/packageDebugResources/compile-file-map.properties

@@ -0,0 +1 @@
+#Wed Jan 21 22:36:12 CET 2026

package/android/build/intermediates/incremental/debug/packageDebugResources/merger.xml

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="utf-8"?>
+<merger version="3"><dataSet aapt-namespace="http://schemas.android.com/apk/res-auto" config="main$Generated" generated="true" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/marco/Lyra-Client/mobile/node_modules/pulse-updates/android/src/main/res"/></dataSet><dataSet aapt-namespace="http://schemas.android.com/apk/res-auto" config="main" generated-set="main$Generated" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/marco/Lyra-Client/mobile/node_modules/pulse-updates/android/src/main/res"/></dataSet><dataSet aapt-namespace="http://schemas.android.com/apk/res-auto" config="debug$Generated" generated="true" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/marco/Lyra-Client/mobile/node_modules/pulse-updates/android/src/debug/res"/></dataSet><dataSet aapt-namespace="http://schemas.android.com/apk/res-auto" config="debug" generated-set="debug$Generated" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/marco/Lyra-Client/mobile/node_modules/pulse-updates/android/src/debug/res"/></dataSet><dataSet aapt-namespace="http://schemas.android.com/apk/res-auto" config="generated$Generated" generated="true" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/marco/Lyra-Client/mobile/node_modules/pulse-updates/android/build/generated/res/resValues/debug"/></dataSet><dataSet aapt-namespace="http://schemas.android.com/apk/res-auto" config="generated" generated-set="generated$Generated" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/marco/Lyra-Client/mobile/node_modules/pulse-updates/android/build/generated/res/resValues/debug"/></dataSet><mergedItems/></merger>

package/android/build/intermediates/incremental/mergeDebugAssets/merger.xml

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="utf-8"?>
+<merger version="3"><dataSet config="main" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/marco/Lyra-Client/mobile/node_modules/pulse-updates/android/src/main/assets"/></dataSet><dataSet config="debug" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/marco/Lyra-Client/mobile/node_modules/pulse-updates/android/src/debug/assets"/></dataSet><dataSet config="generated" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/marco/Lyra-Client/mobile/node_modules/pulse-updates/android/build/intermediates/shader_assets/debug/compileDebugShaders/out"/></dataSet></merger>

package/android/build/intermediates/incremental/mergeDebugJniLibFolders/merger.xml

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="utf-8"?>
+<merger version="3"><dataSet config="main" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/marco/Lyra-Client/mobile/node_modules/pulse-updates/android/src/main/jniLibs"/></dataSet><dataSet config="debug" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/marco/Lyra-Client/mobile/node_modules/pulse-updates/android/src/debug/jniLibs"/></dataSet></merger>

package/android/build/intermediates/incremental/mergeDebugShaders/merger.xml

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="utf-8"?>
+<merger version="3"><dataSet config="main" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/marco/Lyra-Client/mobile/node_modules/pulse-updates/android/src/main/shaders"/></dataSet><dataSet config="debug" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/marco/Lyra-Client/mobile/node_modules/pulse-updates/android/src/debug/shaders"/></dataSet></merger>

package/android/build/intermediates/incremental/mergeReleaseAssets/merger.xml

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="utf-8"?>
+<merger version="3"><dataSet config="main" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/marco/Lyra-Client/mobile/node_modules/pulse-updates/android/src/main/assets"/></dataSet><dataSet config="release" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/marco/Lyra-Client/mobile/node_modules/pulse-updates/android/src/release/assets"/></dataSet><dataSet config="generated" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/marco/Lyra-Client/mobile/node_modules/pulse-updates/android/build/intermediates/shader_assets/release/compileReleaseShaders/out"/></dataSet></merger>