pulse-updates 1.0.0

package/src/NativePulseUpdates.ts

@@ -0,0 +1,52 @@
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+
+export interface Spec extends TurboModule {
+  // Configuration
+  configure(
+    enabled: boolean,
+    updateUrl: string,
+    runtimeVersion: string,
+    checkOnLaunch: string,
+    launchWaitMs: number,
+    channel: string | null,
+    signingKeyId: string | null,
+    signingPublicKey: string | null
+  ): void;
+
+  // Get current state (since constants are captured at init)
+  getStateAsync(): Promise<{
+    isEnabled: boolean;
+    updateId: string | null;
+    runtimeVersion: string | null;
+    channel: string | null;
+    manifestString: string | null;
+    isEmbeddedLaunch: boolean;
+    commitTime: number | null;
+    localAssets?: { [key: string]: string };
+  }>;
+
+  // Methods
+  checkForUpdateAsync(): Promise<{
+    isAvailable: boolean;
+    manifestString?: string;
+    isRollback?: boolean;
+    failedReason?: string;
+  }>;
+
+  fetchUpdateAsync(): Promise<{
+    isNew: boolean;
+    manifestString?: string;
+  }>;
+
+  reloadAsync(): Promise<void>;
+
+  markAppReady(): Promise<void>;
+  reportLaunchFailure(reason: string): Promise<void>;
+
+  // Event emitter
+  addListener(eventName: string): void;
+  removeListeners(count: number): void;
+}
+
+export default TurboModuleRegistry.get<Spec>('PulseUpdates');

package/src/PulseUpdates.ts

@@ -0,0 +1,332 @@
+import { NativeEventEmitter } from 'react-native';
+import NativePulseUpdates from './NativePulseUpdates';
+import type { PulseManifest, PulseUpdatesConfig, UpdateCheckResult, UpdateFetchResult } from './types';
+
+const PulseUpdatesModule = NativePulseUpdates;
+
+// Track configuration and state
+let _isConfigured = false;
+
+// Cached state values
+let _isEnabled = false;
+let _updateId: string | null = null;
+let _runtimeVersion: string | null = null;
+let _channel: string | null = null;
+let _isEmbeddedLaunch = true;
+let _manifest: PulseManifest | null = null;
+let _createdAt: Date | null = null;
+let _localAssets: Record<string, string> | null = null;
+
+/**
+ * Configure pulse-updates with the given options.
+ *
+ * NOTE: This is now OPTIONAL. Configuration is automatically loaded from:
+ * - iOS: Info.plist (keys: PulseUpdatesURL, PulseUpdatesEnabled, etc.)
+ * - Android: AndroidManifest.xml metadata
+ *
+ * Only call this if you need to override the native configuration.
+ */
+export function configure(config: PulseUpdatesConfig): void {
+  if (!PulseUpdatesModule) {
+    console.warn('PulseUpdates native module not found');
+    return;
+  }
+
+  if (_isConfigured) {
+    console.warn('PulseUpdates.configure() has already been called');
+    return;
+  }
+
+  PulseUpdatesModule.configure(
+    config.enabled,
+    config.updateUrl,
+    config.runtimeVersion,
+    config.checkOnLaunch,
+    config.launchWaitMs,
+    config.channel ?? null,
+    config.signingKeyId ?? null,
+    config.signingPublicKey ?? null
+  );
+
+  _isConfigured = true;
+  _isEnabled = config.enabled;
+  _runtimeVersion = config.runtimeVersion;
+}
+
+/**
+ * Whether configure() has been called from JS.
+ * Note: Even if false, native config may be loaded from Info.plist/AndroidManifest.xml
+ */
+export function isConfigured(): boolean {
+  return _isConfigured;
+}
+
+/**
+ * Whether pulse-updates is enabled.
+ */
+export function getIsEnabled(): boolean {
+  return _isEnabled;
+}
+
+// For backwards compatibility, export as mutable (will be updated by refreshStateAsync)
+export let isEnabled = false;
+export let updateId: string | null = null;
+export let runtimeVersion: string | null = null;
+export let channel: string | null = null;
+export let isEmbeddedLaunch = true;
+// expo-updates compatibility: same as isEmbeddedLaunch
+export let isUsingEmbeddedAssets = true;
+export let manifest: PulseManifest | null = null;
+export let createdAt: Date | null = null;
+
+/**
+ * A dictionary of locally available assets for the current update.
+ * Keys are the asset keys from the manifest, values are local file:// URLs.
+ * This can be used by asset resolvers to use locally downloaded or embedded
+ * assets instead of fetching from remote URLs.
+ */
+export let localAssets: Record<string, string> | null = null;
+
+/**
+ * Refresh exported values from native module.
+ * Call this at app startup to get the current state from native.
+ * Configuration is loaded automatically from Info.plist/AndroidManifest.xml.
+ */
+export async function refreshStateAsync(): Promise<void> {
+  if (!PulseUpdatesModule) return;
+
+  try {
+    const state = await PulseUpdatesModule.getStateAsync();
+
+    // Native module returns state based on native config (Info.plist/AndroidManifest.xml)
+    _isEnabled = state.isEnabled ?? false;
+    _updateId = state.updateId ?? null;
+    _runtimeVersion = state.runtimeVersion ?? null;
+    _channel = state.channel ?? null;
+    _isEmbeddedLaunch = state.isEmbeddedLaunch ?? true;
+
+    // Update exported values
+    isEnabled = _isEnabled;
+    updateId = _updateId;
+    runtimeVersion = _runtimeVersion;
+    channel = _channel;
+    isEmbeddedLaunch = _isEmbeddedLaunch;
+    // expo-updates compatibility: same as isEmbeddedLaunch
+    isUsingEmbeddedAssets = _isEmbeddedLaunch;
+
+    if (state.manifestString) {
+      try {
+        _manifest = JSON.parse(state.manifestString);
+        manifest = _manifest;
+      } catch {
+        _manifest = null;
+        manifest = null;
+      }
+    } else {
+      _manifest = null;
+      manifest = null;
+    }
+
+    _createdAt = state.commitTime ? new Date(state.commitTime) : null;
+    createdAt = _createdAt;
+
+    // Read localAssets map for asset resolution
+    _localAssets = state.localAssets ?? null;
+    localAssets = _localAssets;
+  } catch (error) {
+    console.warn('[PulseUpdates] Failed to refresh state:', error);
+    // Keep current values on error
+  }
+}
+
+/**
+ * Check the server for available updates.
+ */
+export async function checkForUpdateAsync(): Promise<UpdateCheckResult> {
+  // if (!_isEnabled) {
+  //   throw new Error('Pulse Updates is not enabled');
+  // }
+
+  // TODO: uncomment after testing
+  // if (__DEV__) {
+  //   throw new Error('Cannot check for updates in development mode');
+  // }
+
+  if (!PulseUpdatesModule) {
+    throw new Error('PulseUpdates native module not found');
+  }
+
+  const result = await PulseUpdatesModule.checkForUpdateAsync();
+
+  if (result.manifestString) {
+    return {
+      isAvailable: result.isAvailable,
+      manifest: JSON.parse(result.manifestString),
+      isRollback: result.isRollback,
+      failedReason: result.failedReason,
+    };
+  }
+
+  return {
+    isAvailable: result.isAvailable,
+    isRollback: result.isRollback,
+    failedReason: result.failedReason,
+  };
+}
+
+/**
+ * Download the most recent update from the server.
+ */
+export async function fetchUpdateAsync(): Promise<UpdateFetchResult> {
+  // if (!_isEnabled) {
+  //   throw new Error('Pulse Updates is not enabled');
+  // }
+
+  // TODO: uncomment after testing
+  // if (__DEV__) {
+  //   throw new Error('Cannot fetch updates in development mode');
+  // }
+
+  if (!PulseUpdatesModule) {
+    throw new Error('PulseUpdates native module not found');
+  }
+
+  const result = await PulseUpdatesModule.fetchUpdateAsync();
+
+  if (result.manifestString) {
+    return {
+      isNew: result.isNew,
+      manifest: JSON.parse(result.manifestString),
+    };
+  }
+
+  return {
+    isNew: result.isNew,
+  };
+}
+
+/**
+ * Reload the app using the most recently downloaded update.
+ */
+export async function reloadAsync(): Promise<void> {
+  // if (!_isEnabled) {
+  //   throw new Error('Pulse Updates is not enabled');
+  // }
+
+  // TODO: uncomment after testing
+  // if (__DEV__) {
+  //   throw new Error('Cannot reload in development mode');
+  // }
+
+  if (!PulseUpdatesModule) {
+    throw new Error('PulseUpdates native module not found');
+  }
+
+  await PulseUpdatesModule.reloadAsync();
+}
+
+/**
+ * Mark the current update as successfully launched.
+ */
+export async function markAppReady(): Promise<void> {
+  if (!_isEnabled) {
+    return;
+  }
+
+  if (!PulseUpdatesModule) {
+    return;
+  }
+
+  await PulseUpdatesModule.markAppReady();
+}
+
+/**
+ * Report a launch failure to trigger rollback on next start.
+ */
+export async function reportLaunchFailure(reason: string): Promise<void> {
+  if (!_isEnabled) {
+    return;
+  }
+
+  if (!PulseUpdatesModule) {
+    return;
+  }
+
+  await PulseUpdatesModule.reportLaunchFailure(reason);
+}
+
+/**
+ * Get the build number from the current update's metadata.
+ */
+export function getUpdateBuild(): string | null {
+  if (!_isEnabled || _isEmbeddedLaunch || !_manifest) {
+    return null;
+  }
+  return (_manifest.metadata?.build as string) ?? null;
+}
+
+/**
+ * Get display version string (e.g., "1.0.0" or "1.0.0.42").
+ */
+export function getDisplayVersion(appVersion: string): string {
+  const build = getUpdateBuild();
+  if (build) {
+    return `${appVersion}.${build}`;
+  }
+  return appVersion;
+}
+
+/**
+ * Get the local file path for an asset by its key.
+ * Returns the local file:// URL if the asset is available locally,
+ * or null if it needs to be fetched from the remote URL.
+ */
+export function getLocalAssetPath(assetKey: string): string | null {
+  if (!_localAssets) {
+    return null;
+  }
+  return _localAssets[assetKey] ?? null;
+}
+
+/**
+ * Get all locally available assets.
+ * Returns a copy of the localAssets map.
+ */
+export function getLocalAssets(): Record<string, string> {
+  return _localAssets ? { ..._localAssets } : {};
+}
+
+// Event emitter for update events
+let eventEmitter: NativeEventEmitter | null = null;
+
+function getEventEmitter(): NativeEventEmitter {
+  if (!eventEmitter && PulseUpdatesModule) {
+    eventEmitter = new NativeEventEmitter(PulseUpdatesModule as any);
+  }
+  return eventEmitter!;
+}
+
+export type UpdateEventType =
+  | 'updateAvailable'
+  | 'updateDownloaded'
+  | 'updateError'
+  | 'noUpdateAvailable';
+
+export interface UpdateEvent {
+  type: UpdateEventType;
+  manifest?: PulseManifest;
+  error?: string;
+}
+
+/**
+ * Add a listener for update events.
+ */
+export function addUpdateListener(
+  listener: (event: UpdateEvent) => void
+): { remove: () => void } {
+  const emitter = getEventEmitter();
+  const subscription = emitter.addListener('PulseUpdatesEvent', listener);
+  return {
+    remove: () => subscription.remove(),
+  };
+}

package/src/assetResolver.ts

@@ -0,0 +1,193 @@
+/**
+ * Pulse Updates Asset Resolver
+ *
+ * Patches React Native's AssetSourceResolver to intercept asset resolution
+ * and serve locally downloaded/embedded assets from OTA updates.
+ *
+ * This approach is based on expo-asset's implementation which patches
+ * AssetSourceResolver.prototype.defaultAsset directly - more reliable than
+ * using setCustomSourceTransformer.
+ *
+ * The patch is applied at module load time to ensure it's in place before
+ * any images start loading.
+ */
+
+// Map of asset key -> local file URL
+let localAssets: Record<string, string> | null = null;
+let isPatched = false;
+
+// Store original method
+let originalDefaultAsset: (() => any) | null = null;
+
+/**
+ * Apply the AssetSourceResolver patch immediately at module load time.
+ * This ensures the patch is in place before any images start loading.
+ */
+function applyPatch(): void {
+  if (isPatched) return;
+
+  try {
+    const AssetSourceResolver = require('react-native/Libraries/Image/AssetSourceResolver').default;
+
+    if (!AssetSourceResolver || !AssetSourceResolver.prototype.defaultAsset) {
+      return;
+    }
+
+    // Save original method
+    originalDefaultAsset = AssetSourceResolver.prototype.defaultAsset;
+
+    // Patch the prototype
+    AssetSourceResolver.prototype.defaultAsset = function(): any {
+      try {
+        // Only try to resolve from local assets if we have any
+        if (localAssets && Object.keys(localAssets).length > 0) {
+          const localUri = resolveLocalAsset(this.asset);
+          if (localUri) {
+            return this.fromSource(localUri);
+          }
+        }
+      } catch (e) {
+        // If local asset resolution fails, fall back to original behavior
+      }
+
+      // Fall back to original behavior
+      try {
+        return originalDefaultAsset!.call(this);
+      } catch (e) {
+        // If original method fails, try calling it as a regular function
+        // This handles edge cases where 'this' context might be lost
+        return originalDefaultAsset!.apply(this, []);
+      }
+    };
+
+    isPatched = true;
+  } catch (e) {
+    // Silently fail - will use default asset resolution
+  }
+}
+
+// Apply patch immediately when module is imported
+applyPatch();
+
+/**
+ * Initialize the asset resolver with the localAssets map.
+ * Call this after PulseUpdates.refreshStateAsync()
+ *
+ * @param assets Map of asset KEY (like "assets/images/icon.png") to local file:// URL
+ */
+export function initializeAssetResolver(assets: Record<string, string> | null): void {
+  localAssets = assets;
+  // Patch is already applied at module load time, just updating the assets map
+}
+
+/**
+ * Update the local assets map (call when a new update is applied)
+ */
+export function updateLocalAssets(assets: Record<string, string> | null): void {
+  localAssets = assets;
+}
+
+/**
+ * Try to resolve an asset from localAssets map
+ * Returns the local file:// URI if found, null otherwise
+ */
+function resolveLocalAsset(asset: any): string | null {
+  if (!localAssets || !asset) {
+    return null;
+  }
+
+  // Construct possible keys to look up
+  const keysToTry = buildAssetKeys(asset);
+
+  for (const key of keysToTry) {
+    if (localAssets[key]) {
+      // Debug: log successful resolution
+      if (__DEV__) {
+        console.log(`[PulseAssetResolver] Resolved ${asset.name}.${asset.type} with key=${key.substring(0, 16)}...`);
+      }
+      return localAssets[key];
+    }
+  }
+
+  // Debug: log failed resolution
+  if (__DEV__) {
+    console.log(`[PulseAssetResolver] MISS for ${asset.name}.${asset.type}`, {
+      triedKeys: keysToTry.map(k => k.substring(0, 16) + '...'),
+      localAssetsCount: Object.keys(localAssets).length,
+      localAssetsSample: Object.keys(localAssets).slice(0, 3).map(k => k.substring(0, 16) + '...')
+    });
+  }
+
+  return null;
+}
+
+/**
+ * Build possible asset keys from Metro asset metadata
+ * Metro assets have: name, type, httpServerLocation, hash, scales
+ *
+ * Key format in localAssets:
+ * - MD5 hash (key field from manifest) - what expo-asset/Metro uses
+ * - SHA256 hash (hash field from manifest) - for integrity verification
+ * - Path-based key for legacy compatibility
+ */
+function buildAssetKeys(asset: any): string[] {
+  const keys: string[] = [];
+  const { name, type, httpServerLocation, hash, fileHashes } = asset;
+
+  // 1. Try Metro's hash directly (MD5 hash of file contents)
+  // This is the primary lookup method matching expo-asset
+  if (hash) {
+    keys.push(hash);
+  }
+
+  // 2. Try fileHashes if available (Metro may provide multiple hash types)
+  if (fileHashes) {
+    Object.values(fileHashes).forEach((h: any) => {
+      if (typeof h === 'string' && h !== hash) {
+        keys.push(h);
+      }
+    });
+  }
+
+  // Build path-based keys
+  let location = httpServerLocation || '';
+
+  // Remove leading slash
+  if (location.startsWith('/')) {
+    location = location.slice(1);
+  }
+
+  // 2. Standard key: assets/path/name.type
+  if (location) {
+    keys.push(`${location}/${name}.${type}`);
+  }
+
+  // 3. With assets/ prefix if not present
+  if (location && !location.startsWith('assets')) {
+    keys.push(`assets/${location}/${name}.${type}`);
+  }
+
+  // 4. Without any prefix
+  keys.push(`${name}.${type}`);
+
+  // 5. Try with scale suffixes for retina assets
+  const scales = asset.scales || [1];
+  for (const scale of scales) {
+    if (scale !== 1) {
+      const scaleSuffix = `@${scale}x`;
+      if (location) {
+        keys.push(`${location}/${name}${scaleSuffix}.${type}`);
+        if (!location.startsWith('assets')) {
+          keys.push(`assets/${location}/${name}${scaleSuffix}.${type}`);
+        }
+      }
+    }
+  }
+
+  return keys;
+}
+
+export default {
+  initializeAssetResolver,
+  updateLocalAssets,
+};

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './PulseUpdates';
+export * from './types';
+export { usePulseUpdates } from './usePulseUpdates';
+export { initializeAssetResolver, updateLocalAssets } from './assetResolver';

package/src/types.ts

@@ -0,0 +1,78 @@
+export interface PulseManifest {
+  updateId: string;
+  runtimeVersion: string;
+  createdAt: string;
+  bundle?: PulseBundle;
+  assets: PulseAsset[];
+  metadata?: Record<string, unknown>;
+  signature?: PulseSignature;
+
+  // Legacy fields
+  id?: string;
+  launchAsset?: PulseAsset;
+  extra?: Record<string, unknown>;
+}
+
+export interface PulseAsset {
+  key?: string;
+  hash: string;
+  url: string;
+  contentType: string;
+  fileExtension?: string;
+}
+
+export interface PulseBundle {
+  hash: string;
+  url: string;
+  contentType: string;
+}
+
+export interface PulseSignature {
+  alg: string;
+  keyId: string;
+  sig: string;
+}
+
+export interface UpdateCheckResult {
+  isAvailable: boolean;
+  manifest?: PulseManifest;
+  isRollback?: boolean;
+  failedReason?: string;
+}
+
+export interface UpdateFetchResult {
+  isNew: boolean;
+  manifest?: PulseManifest;
+}
+
+export interface PulseUpdatesConfig {
+  enabled: boolean;
+  updateUrl: string;
+  runtimeVersion: string;
+  checkOnLaunch: 'ALWAYS' | 'WIFI_ONLY' | 'NEVER';
+  launchWaitMs: number;
+  channel?: string;
+  signingKeyId?: string;
+  signingPublicKey?: string;
+}
+
+export interface PulseUpdatesState {
+  isEnabled: boolean;
+  isChecking: boolean;
+  isDownloading: boolean;
+  updateId: string | null;
+  runtimeVersion: string | null;
+  channel: string | null;
+  manifest: PulseManifest | null;
+  isEmbeddedLaunch: boolean;
+  createdAt: Date | null;
+  lastCheckTime: Date | null;
+  availableUpdate: PulseManifest | null;
+  downloadedUpdate: PulseManifest | null;
+  error: Error | null;
+  /**
+   * A dictionary of locally available assets for the current update.
+   * Keys are the asset keys from the manifest, values are local file:// URLs.
+   */
+  localAssets: Record<string, string> | null;
+}