@otaupdate/react-native 1.0.0

package/ios/OtaUpdateInstaller.m

@@ -0,0 +1,278 @@
+#import "OtaUpdateInstaller.h"
+#import <CommonCrypto/CommonDigest.h>
+#import <SSZipArchive/SSZipArchive.h>
+
+NSString *const OtaUpdateErrorDomain = @"com.otaupdate.error";
+
+static NSArray<NSString *> *OtaBundleCandidates(void) {
+  return @[ @"main.jsbundle", @"index.ios.bundle", @"index.bundle" ];
+}
+
+static NSError *OtaError(NSInteger code, NSString *message) {
+  return [NSError errorWithDomain:OtaUpdateErrorDomain
+                             code:code
+                         userInfo:@{NSLocalizedDescriptionKey : message}];
+}
+
+#pragma mark - Download delegate
+
+/**
+ * NSURLSessionDownloadTask streams to a temp file for us, which keeps large
+ * bundles off the heap. Hashing happens after the transfer completes.
+ */
+@interface OtaDownloadDelegate : NSObject <NSURLSessionDownloadDelegate>
+@property (nonatomic, copy) void (^progressBlock)(long long received, long long total);
+@property (nonatomic, copy) void (^completionBlock)(NSURL *_Nullable location, NSError *_Nullable error);
+@property (nonatomic, assign) long long lastReported;
+@end
+
+@implementation OtaDownloadDelegate
+
+- (void)URLSession:(NSURLSession *)session
+             downloadTask:(NSURLSessionDownloadTask *)downloadTask
+             didWriteData:(int64_t)bytesWritten
+        totalBytesWritten:(int64_t)totalBytesWritten
+totalBytesExpectedToWrite:(int64_t)totalBytesExpectedToWrite {
+  if (!self.progressBlock) return;
+  // Throttle to ~1% steps; the bridge cannot keep up with per-chunk events.
+  int64_t step = totalBytesExpectedToWrite > 0 ? totalBytesExpectedToWrite / 100 : 0;
+  if (step <= 0 || totalBytesWritten - self.lastReported >= step ||
+      totalBytesWritten == totalBytesExpectedToWrite) {
+    self.lastReported = totalBytesWritten;
+    self.progressBlock(totalBytesWritten, totalBytesExpectedToWrite);
+  }
+}
+
+- (void)URLSession:(NSURLSession *)session
+              downloadTask:(NSURLSessionDownloadTask *)downloadTask
+ didFinishDownloadingToURL:(NSURL *)location {
+  NSHTTPURLResponse *response = (NSHTTPURLResponse *)downloadTask.response;
+  if ([response isKindOfClass:[NSHTTPURLResponse class]] &&
+      (response.statusCode < 200 || response.statusCode > 299)) {
+    self.completionBlock(nil, OtaError(1001, [NSString stringWithFormat:@"Bundle download failed with HTTP %ld",
+                                                                       (long)response.statusCode]));
+    return;
+  }
+
+  // `location` is deleted as soon as this method returns — move it first.
+  NSURL *stable = [[NSURL fileURLWithPath:NSTemporaryDirectory()]
+      URLByAppendingPathComponent:[NSString stringWithFormat:@"ota-%@.zip", [[NSUUID UUID] UUIDString]]];
+  NSError *moveError = nil;
+  [[NSFileManager defaultManager] moveItemAtURL:location toURL:stable error:&moveError];
+  self.completionBlock(moveError ? nil : stable, moveError);
+}
+
+- (void)URLSession:(NSURLSession *)session
+                    task:(NSURLSessionTask *)task
+    didCompleteWithError:(NSError *)error {
+  if (error) self.completionBlock(nil, error);
+}
+
+@end
+
+#pragma mark - Installer
+
+@implementation OtaUpdateInstaller
+
++ (void)installUpdateWithStore:(OtaUpdateStore *)store
+                   downloadURL:(NSString *)downloadURL
+                  expectedHash:(NSString *)expectedHash
+                      progress:(void (^)(long long, long long))progress
+                    completion:(void (^)(NSString *_Nullable, long long, NSError *_Nullable))completion {
+
+  if ([store hasFailed:expectedHash]) {
+    completion(nil, 0,
+               OtaError(1005, [NSString stringWithFormat:
+                                            @"Refusing to reinstall %@ — a previous attempt failed to boot",
+                                            expectedHash]));
+    return;
+  }
+
+  NSURL *targetDir = [store packageDirectoryForHash:expectedHash];
+  NSString *existing = [self resolveBundleInDirectory:targetDir];
+  if (existing) {
+    // Downloaded and verified on an earlier attempt.
+    completion(existing, [self directorySize:targetDir], nil);
+    return;
+  }
+
+  NSURL *url = [NSURL URLWithString:downloadURL];
+  if (!url) {
+    completion(nil, 0, OtaError(1002, @"The download URL returned by the server is not valid"));
+    return;
+  }
+
+  OtaDownloadDelegate *delegate = [[OtaDownloadDelegate alloc] init];
+  delegate.progressBlock = progress;
+
+  NSURLSessionConfiguration *configuration = [NSURLSessionConfiguration defaultSessionConfiguration];
+  configuration.timeoutIntervalForRequest = 60;
+  configuration.timeoutIntervalForResource = 600;
+  NSURLSession *session = [NSURLSession sessionWithConfiguration:configuration
+                                                        delegate:delegate
+                                                   delegateQueue:nil];
+
+  __block BOOL finished = NO;
+  delegate.completionBlock = ^(NSURL *location, NSError *error) {
+    // The delegate can fire both didFinishDownloading and didCompleteWithError.
+    if (finished) return;
+    finished = YES;
+    [session finishTasksAndInvalidate];
+
+    if (error || !location) {
+      completion(nil, 0, error ?: OtaError(1003, @"Bundle download failed"));
+      return;
+    }
+
+    NSError *installError = nil;
+    long long size = 0;
+    NSString *bundlePath = [self verifyAndUnzip:location
+                                          store:store
+                                   expectedHash:expectedHash
+                                           size:&size
+                                          error:&installError];
+    [[NSFileManager defaultManager] removeItemAtURL:location error:nil];
+    completion(bundlePath, size, installError);
+  };
+
+  [[session downloadTaskWithURL:url] resume];
+}
+
++ (nullable NSString *)verifyAndUnzip:(NSURL *)zipURL
+                                store:(OtaUpdateStore *)store
+                         expectedHash:(NSString *)expectedHash
+                                 size:(long long *)outSize
+                                error:(NSError **)outError {
+  NSString *actualHash = [self sha256OfFileAtURL:zipURL];
+  if (!actualHash) {
+    if (outError) *outError = OtaError(1004, @"Could not read the downloaded bundle");
+    return nil;
+  }
+  if ([actualHash caseInsensitiveCompare:expectedHash] != NSOrderedSame) {
+    if (outError) {
+      *outError = OtaError(1006, [NSString stringWithFormat:
+                                               @"Bundle integrity check failed: expected %@ but downloaded %@",
+                                               expectedHash, actualHash]);
+    }
+    return nil;
+  }
+
+  NSURL *targetDir = [store packageDirectoryForHash:expectedHash];
+  [[NSFileManager defaultManager] removeItemAtURL:targetDir error:nil];
+  [[NSFileManager defaultManager] createDirectoryAtURL:targetDir
+                           withIntermediateDirectories:YES
+                                            attributes:nil
+                                                 error:nil];
+
+  NSError *unzipError = nil;
+  BOOL ok = [SSZipArchive unzipFileAtPath:zipURL.path
+                            toDestination:targetDir.path
+                                overwrite:YES
+                                 password:nil
+                                    error:&unzipError];
+  if (!ok) {
+    [[NSFileManager defaultManager] removeItemAtURL:targetDir error:nil];
+    if (outError) {
+      *outError = unzipError ?: OtaError(1007, @"Could not unzip the release package");
+    }
+    return nil;
+  }
+
+  NSString *bundlePath = [self resolveBundleInDirectory:targetDir];
+  if (!bundlePath) {
+    [[NSFileManager defaultManager] removeItemAtURL:targetDir error:nil];
+    if (outError) {
+      *outError = OtaError(1008, [NSString stringWithFormat:
+                                               @"The release package contains no JS bundle (looked for %@)",
+                                               [OtaBundleCandidates() componentsJoinedByString:@", "]]);
+    }
+    return nil;
+  }
+
+  if (outSize) *outSize = [self directorySize:targetDir];
+  return bundlePath;
+}
+
+/** Streams the file through CC_SHA256 so memory stays flat for large bundles. */
++ (nullable NSString *)sha256OfFileAtURL:(NSURL *)url {
+  NSFileHandle *handle = [NSFileHandle fileHandleForReadingAtPath:url.path];
+  if (!handle) return nil;
+
+  CC_SHA256_CTX context;
+  CC_SHA256_Init(&context);
+
+  const NSUInteger chunkSize = 64 * 1024;
+  @try {
+    while (YES) {
+      @autoreleasepool {
+        NSData *chunk = [handle readDataOfLength:chunkSize];
+        if (chunk.length == 0) break;
+        CC_SHA256_Update(&context, chunk.bytes, (CC_LONG)chunk.length);
+      }
+    }
+  } @finally {
+    [handle closeFile];
+  }
+
+  unsigned char digest[CC_SHA256_DIGEST_LENGTH];
+  CC_SHA256_Final(digest, &context);
+
+  NSMutableString *hex = [NSMutableString stringWithCapacity:CC_SHA256_DIGEST_LENGTH * 2];
+  for (int i = 0; i < CC_SHA256_DIGEST_LENGTH; i++) [hex appendFormat:@"%02x", digest[i]];
+  return hex;
+}
+
+/**
+ * Finds the JS bundle inside an extracted package, tolerating archives that
+ * wrap everything in a single top-level folder.
+ */
++ (nullable NSString *)resolveBundleInDirectory:(NSURL *)directory {
+  NSFileManager *fm = [NSFileManager defaultManager];
+  BOOL isDirectory = NO;
+  if (![fm fileExistsAtPath:directory.path isDirectory:&isDirectory] || !isDirectory) return nil;
+
+  for (NSString *name in OtaBundleCandidates()) {
+    NSString *candidate = [directory.path stringByAppendingPathComponent:name];
+    if ([fm fileExistsAtPath:candidate]) return candidate;
+  }
+
+  NSArray<NSURL *> *children = [fm contentsOfDirectoryAtURL:directory
+                                 includingPropertiesForKeys:@[ NSURLIsDirectoryKey ]
+                                                    options:NSDirectoryEnumerationSkipsHiddenFiles
+                                                      error:nil];
+  if (children.count == 1) {
+    NSNumber *dirFlag = nil;
+    [children.firstObject getResourceValue:&dirFlag forKey:NSURLIsDirectoryKey error:nil];
+    if (dirFlag.boolValue) {
+      NSString *nested = [self resolveBundleInDirectory:children.firstObject];
+      if (nested) return nested;
+    }
+  }
+
+  NSDirectoryEnumerator *enumerator = [fm enumeratorAtURL:directory
+                               includingPropertiesForKeys:nil
+                                                  options:NSDirectoryEnumerationSkipsHiddenFiles
+                                             errorHandler:nil];
+  for (NSURL *file in enumerator) {
+    NSString *ext = file.pathExtension;
+    if ([ext isEqualToString:@"jsbundle"] || [ext isEqualToString:@"bundle"]) return file.path;
+  }
+  return nil;
+}
+
++ (long long)directorySize:(NSURL *)directory {
+  long long total = 0;
+  NSDirectoryEnumerator *enumerator =
+      [[NSFileManager defaultManager] enumeratorAtURL:directory
+                           includingPropertiesForKeys:@[ NSURLFileSizeKey ]
+                                              options:0
+                                         errorHandler:nil];
+  for (NSURL *file in enumerator) {
+    NSNumber *size = nil;
+    [file getResourceValue:&size forKey:NSURLFileSizeKey error:nil];
+    total += size.longLongValue;
+  }
+  return total;
+}
+
+@end

package/ios/OtaUpdateStore.h

@@ -0,0 +1,69 @@
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * On-disk state for downloaded JS bundles, and the rollback state machine.
+ *
+ * Layout under Application Support/OtaUpdate:
+ *   status.json          the state below
+ *   packages/<sha256>/   one unzipped release each
+ *
+ *   install()           -> pending = hash, isLoading = NO
+ *   next launch         -> promote: current = pending, isLoading = YES
+ *   notifyAppReady()    -> confirm: lastConfirmed = current, pending = nil
+ *   launch while loading-> the last boot never confirmed: roll back and
+ *                          blacklist the bad hash
+ */
+@interface OtaUpdateStore : NSObject
+
++ (instancetype)sharedStore;
+
+/** YES when this launch swapped in a freshly installed bundle. */
+@property (nonatomic, readonly) BOOL isFirstRunOfUpdate;
+
+@property (nonatomic, copy, readonly, nullable) NSString *currentHash;
+@property (nonatomic, copy, readonly, nullable) NSString *lastConfirmedHash;
+@property (nonatomic, copy, readonly, nullable) NSString *pendingHash;
+
+/** Runs once per process launch, before the bundle URL is resolved. YES if it rolled back. */
+- (BOOL)initializeAfterRestart;
+
+/**
+ * Promote a freshly installed package without ever treating the call as a
+ * failed boot. Used when the bundle URL is resolved again inside the same
+ * process — an IMMEDIATE or ON_NEXT_RESUME reload.
+ */
+- (BOOL)promotePendingIfAny;
+
+- (void)notifyApplicationReady;
+- (void)markPending:(NSString *)packageHash;
+- (BOOL)hasFailed:(NSString *)packageHash;
+- (BOOL)isPending;
+
+- (NSURL *)packageDirectoryForHash:(NSString *)packageHash;
+- (NSURL *)rootDirectory;
+
+- (void)recordPackageWithHash:(NSString *)packageHash
+                        label:(NSString *)label
+                   bundlePath:(NSString *)bundlePath
+                  description:(nullable NSString *)description
+                  isMandatory:(BOOL)isMandatory
+                         size:(long long)size
+                   appVersion:(NSString *)appVersion;
+
+- (nullable NSDictionary *)packageInfoForHash:(nullable NSString *)packageHash;
+
+/** Absolute path of the bundle to load, or nil to use the one in the binary. */
+- (nullable NSString *)currentBundlePath;
+
+- (void)deletePackage:(NSString *)packageHash;
+- (void)pruneOldPackages;
+- (void)reset;
+
+/** Stable random per-install id used for rollout bucketing. */
+- (NSString *)clientUniqueId;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/OtaUpdateStore.m

@@ -0,0 +1,283 @@
+#import "OtaUpdateStore.h"
+
+static NSString *const kClientIdKey = @"com.otaupdate.clientUniqueId";
+static NSString *const kLogTag = @"[OtaUpdate]";
+
+@interface OtaUpdateStore ()
+@property (nonatomic, copy, nullable) NSString *currentHash;
+@property (nonatomic, copy, nullable) NSString *lastConfirmedHash;
+@property (nonatomic, copy, nullable) NSString *pendingHash;
+@property (nonatomic, assign) BOOL pendingIsLoading;
+@property (nonatomic, strong) NSMutableSet<NSString *> *failedHashes;
+@property (nonatomic, strong) NSMutableDictionary<NSString *, NSDictionary *> *packages;
+@property (nonatomic, assign) BOOL isFirstRunOfUpdate;
+@property (nonatomic, strong) NSURL *rootURL;
+@end
+
+@implementation OtaUpdateStore
+
++ (instancetype)sharedStore {
+  static OtaUpdateStore *shared = nil;
+  static dispatch_once_t token;
+  dispatch_once(&token, ^{
+    shared = [[OtaUpdateStore alloc] init];
+  });
+  return shared;
+}
+
+- (instancetype)init {
+  if (self = [super init]) {
+    _failedHashes = [NSMutableSet set];
+    _packages = [NSMutableDictionary dictionary];
+
+    // Application Support is excluded from iCloud backup churn concerns and is
+    // the right place for regenerable app data.
+    NSURL *appSupport = [[NSFileManager defaultManager] URLsForDirectory:NSApplicationSupportDirectory
+                                                               inDomains:NSUserDomainMask].firstObject;
+    _rootURL = [appSupport URLByAppendingPathComponent:@"OtaUpdate" isDirectory:YES];
+    [[NSFileManager defaultManager] createDirectoryAtURL:[self packagesRoot]
+                             withIntermediateDirectories:YES
+                                              attributes:nil
+                                                   error:nil];
+    [self load];
+  }
+  return self;
+}
+
+- (NSURL *)rootDirectory {
+  return self.rootURL;
+}
+
+- (NSURL *)packagesRoot {
+  return [self.rootURL URLByAppendingPathComponent:@"packages" isDirectory:YES];
+}
+
+- (NSURL *)statusURL {
+  return [self.rootURL URLByAppendingPathComponent:@"status.json"];
+}
+
+#pragma mark - Persistence
+
+- (void)load {
+  NSData *data = [NSData dataWithContentsOfURL:[self statusURL]];
+  if (!data) return;
+
+  NSError *error = nil;
+  NSDictionary *json = [NSJSONSerialization JSONObjectWithData:data options:0 error:&error];
+  if (![json isKindOfClass:[NSDictionary class]]) {
+    // A corrupt status file must never stop the app booting.
+    NSLog(@"%@ status.json unreadable, resetting OTA state (%@)", kLogTag, error.localizedDescription);
+    [self reset];
+    return;
+  }
+
+  self.currentHash = [json[@"currentHash"] isKindOfClass:[NSString class]] ? json[@"currentHash"] : nil;
+  self.lastConfirmedHash = [json[@"lastConfirmedHash"] isKindOfClass:[NSString class]] ? json[@"lastConfirmedHash"] : nil;
+  self.pendingHash = [json[@"pendingHash"] isKindOfClass:[NSString class]] ? json[@"pendingHash"] : nil;
+  self.pendingIsLoading = [json[@"pendingIsLoading"] boolValue];
+
+  NSArray *failed = json[@"failedHashes"];
+  if ([failed isKindOfClass:[NSArray class]]) [self.failedHashes addObjectsFromArray:failed];
+
+  NSDictionary *pkgs = json[@"packages"];
+  if ([pkgs isKindOfClass:[NSDictionary class]]) [self.packages addEntriesFromDictionary:pkgs];
+}
+
+- (void)save {
+  NSMutableDictionary *json = [NSMutableDictionary dictionary];
+  json[@"currentHash"] = self.currentHash ?: [NSNull null];
+  json[@"lastConfirmedHash"] = self.lastConfirmedHash ?: [NSNull null];
+  json[@"pendingHash"] = self.pendingHash ?: [NSNull null];
+  json[@"pendingIsLoading"] = @(self.pendingIsLoading);
+  json[@"failedHashes"] = self.failedHashes.allObjects;
+  json[@"packages"] = self.packages;
+
+  NSError *error = nil;
+  NSData *data = [NSJSONSerialization dataWithJSONObject:json options:0 error:&error];
+  if (!data) {
+    NSLog(@"%@ failed to serialise OTA state: %@", kLogTag, error.localizedDescription);
+    return;
+  }
+  [[NSFileManager defaultManager] createDirectoryAtURL:self.rootURL
+                           withIntermediateDirectories:YES
+                                            attributes:nil
+                                                 error:nil];
+  [data writeToURL:[self statusURL] atomically:YES];
+}
+
+#pragma mark - Rollback state machine
+
+- (BOOL)initializeAfterRestart {
+  @synchronized(self) {
+    NSString *pending = self.pendingHash;
+    if (!pending) return NO;
+
+    if (self.pendingIsLoading) {
+      NSLog(@"%@ update %@ failed to become ready — rolling back", kLogTag, pending);
+      [self.failedHashes addObject:pending];
+      self.currentHash = self.lastConfirmedHash;
+      self.pendingHash = nil;
+      self.pendingIsLoading = NO;
+      self.isFirstRunOfUpdate = NO;
+      [self save];
+      [self deletePackage:pending];
+      return YES;
+    }
+
+    [self promotePendingIfAny];
+    return NO;
+  }
+}
+
+- (BOOL)promotePendingIfAny {
+  @synchronized(self) {
+    NSString *pending = self.pendingHash;
+    if (!pending || self.pendingIsLoading) return NO;
+
+    NSLog(@"%@ booting into pending update %@", kLogTag, pending);
+    self.currentHash = pending;
+    self.pendingIsLoading = YES;
+    self.isFirstRunOfUpdate = YES;
+    [self save];
+    return YES;
+  }
+}
+
+- (void)notifyApplicationReady {
+  @synchronized(self) {
+    if (!self.pendingHash) return;
+    NSLog(@"%@ update %@ confirmed healthy", kLogTag, self.pendingHash);
+    self.lastConfirmedHash = self.currentHash;
+    self.pendingHash = nil;
+    self.pendingIsLoading = NO;
+    [self save];
+  }
+}
+
+- (void)markPending:(NSString *)packageHash {
+  @synchronized(self) {
+    self.pendingHash = packageHash;
+    self.pendingIsLoading = NO;
+    [self save];
+  }
+}
+
+- (BOOL)hasFailed:(NSString *)packageHash {
+  @synchronized(self) {
+    return [self.failedHashes containsObject:packageHash];
+  }
+}
+
+- (BOOL)isPending {
+  @synchronized(self) {
+    return self.pendingHash != nil;
+  }
+}
+
+#pragma mark - Packages
+
+- (NSURL *)packageDirectoryForHash:(NSString *)packageHash {
+  return [[self packagesRoot] URLByAppendingPathComponent:packageHash isDirectory:YES];
+}
+
+- (void)recordPackageWithHash:(NSString *)packageHash
+                        label:(NSString *)label
+                   bundlePath:(NSString *)bundlePath
+                  description:(NSString *)description
+                  isMandatory:(BOOL)isMandatory
+                         size:(long long)size
+                   appVersion:(NSString *)appVersion {
+  @synchronized(self) {
+    self.packages[packageHash] = @{
+      @"label" : label ?: @"",
+      @"bundlePath" : bundlePath ?: @"",
+      @"description" : description ?: [NSNull null],
+      @"isMandatory" : @(isMandatory),
+      @"size" : @(size),
+      @"appVersion" : appVersion ?: @"",
+      @"installedAt" : @([[NSDate date] timeIntervalSince1970] * 1000),
+    };
+    [self save];
+  }
+}
+
+- (NSDictionary *)packageInfoForHash:(NSString *)packageHash {
+  @synchronized(self) {
+    return packageHash ? self.packages[packageHash] : nil;
+  }
+}
+
+- (NSString *)currentBundlePath {
+  @synchronized(self) {
+    if (!self.currentHash) return nil;
+    NSDictionary *info = self.packages[self.currentHash];
+    if (!info) return nil;
+
+    NSString *path = info[@"bundlePath"];
+    if (path.length > 0 && [[NSFileManager defaultManager] fileExistsAtPath:path]) return path;
+
+    // The file went missing (device cleanup, restore from backup, ...).
+    NSLog(@"%@ bundle for %@ is missing on disk — using the binary bundle", kLogTag, self.currentHash);
+    self.currentHash = [self.lastConfirmedHash isEqualToString:self.currentHash] ? nil : self.lastConfirmedHash;
+    [self save];
+
+    NSString *fallback = self.currentHash ? self.packages[self.currentHash][@"bundlePath"] : nil;
+    return (fallback.length > 0 && [[NSFileManager defaultManager] fileExistsAtPath:fallback]) ? fallback : nil;
+  }
+}
+
+- (void)deletePackage:(NSString *)packageHash {
+  @synchronized(self) {
+    [self.packages removeObjectForKey:packageHash];
+    [[NSFileManager defaultManager] removeItemAtURL:[self packageDirectoryForHash:packageHash] error:nil];
+    [self save];
+  }
+}
+
+- (void)pruneOldPackages {
+  @synchronized(self) {
+    NSMutableSet *keep = [NSMutableSet set];
+    if (self.currentHash) [keep addObject:self.currentHash];
+    if (self.lastConfirmedHash) [keep addObject:self.lastConfirmedHash];
+    if (self.pendingHash) [keep addObject:self.pendingHash];
+
+    for (NSString *hash in self.packages.allKeys) {
+      if ([keep containsObject:hash]) continue;
+      [self.packages removeObjectForKey:hash];
+      [[NSFileManager defaultManager] removeItemAtURL:[self packageDirectoryForHash:hash] error:nil];
+    }
+    [self save];
+  }
+}
+
+- (void)reset {
+  @synchronized(self) {
+    self.currentHash = nil;
+    self.lastConfirmedHash = nil;
+    self.pendingHash = nil;
+    self.pendingIsLoading = NO;
+    self.isFirstRunOfUpdate = NO;
+    [self.failedHashes removeAllObjects];
+    [self.packages removeAllObjects];
+    [[NSFileManager defaultManager] removeItemAtURL:[self packagesRoot] error:nil];
+    [[NSFileManager defaultManager] createDirectoryAtURL:[self packagesRoot]
+                             withIntermediateDirectories:YES
+                                              attributes:nil
+                                                   error:nil];
+    [self save];
+  }
+}
+
+#pragma mark - Device identity
+
+- (NSString *)clientUniqueId {
+  NSUserDefaults *defaults = [NSUserDefaults standardUserDefaults];
+  NSString *existing = [defaults stringForKey:kClientIdKey];
+  if (existing.length > 0) return existing;
+
+  NSString *identifier = [[NSUUID UUID] UUIDString];
+  [defaults setObject:identifier forKey:kClientIdKey];
+  return identifier;
+}
+
+@end

package/lib/OtaUpdate.d.ts

@@ -0,0 +1,28 @@
+import { SyncStatus, type CheckResult, type CurrentPackage, type OtaConfiguration, type OtaOptions, type SyncOptions } from './types';
+/** Asks the server whether a newer bundle applies to this device. */
+export declare function checkForUpdate(deploymentKey?: string): Promise<CheckResult>;
+/**
+ * Check → download → install, in one call. Safe to call repeatedly; concurrent
+ * calls share the in-flight run rather than downloading twice.
+ */
+export declare function sync(options?: SyncOptions): Promise<SyncStatus>;
+/**
+ * Confirms the running bundle works. Until this is called, the next app start
+ * treats the update as broken and rolls back to the previous bundle.
+ *
+ * Call it once your app has rendered and its critical startup path has run.
+ */
+export declare function notifyAppReady(): Promise<void>;
+export declare function restartApp(onlyIfUpdateIsPending?: boolean): Promise<void>;
+export declare function getCurrentPackage(): Promise<CurrentPackage | null>;
+/** Wipes every downloaded package and reverts to the bundle inside the binary. */
+export declare function clearUpdates(): Promise<void>;
+export declare function getConfig(): Promise<OtaConfiguration>;
+/**
+ * Starts the app-start / app-resume sync loop. `withOtaUpdate` calls this for
+ * you; call it directly if you are not using the HOC.
+ */
+export declare function startAutoSync(options?: OtaOptions): () => void;
+/** Test seam — resets memoised configuration and sync state. */
+export declare function __resetForTests(): void;
+//# sourceMappingURL=OtaUpdate.d.ts.map

package/lib/OtaUpdate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OtaUpdate.d.ts","sourceRoot":"","sources":["../src/OtaUpdate.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,UAAU,EACV,KAAK,WAAW,EAChB,KAAK,cAAc,EAGnB,KAAK,gBAAgB,EACrB,KAAK,UAAU,EAEf,KAAK,WAAW,EACjB,MAAM,SAAS,CAAC;AAmGjB,qEAAqE;AACrE,wBAAsB,cAAc,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAOjF;AAED;;;GAGG;AACH,wBAAsB,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CAUzE;AAqDD;;;;;GAKG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAcpD;AAED,wBAAsB,UAAU,CAAC,qBAAqB,UAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAE7E;AAED,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAaxE;AAED,kFAAkF;AAClF,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAElD;AAED,wBAAsB,SAAS,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAE3D;AAMD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,UAAe,GAAG,MAAM,IAAI,CAoClE;AAED,gEAAgE;AAChE,wBAAgB,eAAe,IAAI,IAAI,CAKtC"}