@sigx/lynx-updates 0.6.1 → 0.7.0

package/dist/updates.js

@@ -1,21 +1,30 @@
 /**
- * Public `Updates` API — a thin facade over the controller, the store and
- * the native module. See the package README for usage.
+ * Public API — `defineUpdates()` (the boot-time declaration, in the
+ * `defineApp`/`defineRoutes` family) and the `Updates` runtime object (a
+ * thin facade over the controller, the store and the native module, in the
+ * `Haptics`/`Storage` native-module family). See the package README.
  */
 import * as controller from './controller.js';
 import { getCurrentUpdate, nativeAvailable } from './native.js';
 import { addListener, getStateSnapshot } from './state.js';
+/**
+ * Declare the OTA update behavior for this app. Call once in `main.tsx`
+ * before `defineApp` — idempotent and synchronous; re-declaring updates the
+ * config but never re-runs the boot work (markReady / launch check).
+ * Kicks off the configured mode's automatic behavior on a deferred task
+ * (never blocks first paint). No-ops gracefully (with one warning) when the
+ * native module is absent (web preview, tests).
+ *
+ * @example
+ * ```tsx
+ * defineUpdates({ provider: { url: 'https://cdn.example.com/updates.json' } });
+ * defineApp(<App />).mount(null);
+ * ```
+ */
+export function defineUpdates(config) {
+    controller.configure(config);
+}
 export const Updates = {
-    /**
-     * Configure the updates client. Idempotent and synchronous; must run
-     * before any other call — typically in `main.tsx` before `defineApp`.
-     * Kicks off the configured mode's automatic behavior on a deferred task
-     * (never blocks first paint). No-ops gracefully (with one warning) when
-     * the native module is absent (web preview, tests).
-     */
-    configure(config) {
-        controller.configure(config);
-    },
     /** Ask the provider for the best available update. Works in every mode. */
     checkForUpdate() {
         return controller.checkForUpdate();
@@ -37,7 +46,7 @@ export const Updates = {
     },
     /**
      * Health signal: commits the pending update so native stops counting
-     * launch attempts against it. Called automatically after configure()
+     * launch attempts against it. Called automatically after defineUpdates()
      * unless `autoMarkReady: false`. Safe to call repeatedly.
      */
     markReady() {

package/dist/updates.js.map

@@ -1 +1 @@
-{"version":3,"file":"updates.js","sourceRoot":"","sources":["../src/updates.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAU3D,MAAM,CAAC,MAAM,OAAO,GAAG;IACnB;;;;;;OAMG;IACH,SAAS,CAAC,MAAqB;QAC3B,UAAU,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACjC,CAAC;IAED,2EAA2E;IAC3E,cAAc;QACV,OAAO,UAAU,CAAC,cAAc,EAAE,CAAC;IACvC,CAAC;IAED;;;OAGG;IACH,QAAQ,CAAC,QAAyB;QAC9B,OAAO,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACzC,CAAC;IAED;;;;OAIG;IACH,KAAK;QACD,OAAO,UAAU,CAAC,KAAK,EAAE,CAAC;IAC9B,CAAC;IAED;;;;OAIG;IACH,SAAS;QACL,OAAO,UAAU,CAAC,SAAS,EAAE,CAAC;IAClC,CAAC;IAED,uEAAuE;IACvE,mBAAmB;QACf,OAAO,gBAAgB,EAAE,CAAC;IAC9B,CAAC;IAED,0EAA0E;IAC1E,YAAY;QACR,OAAO,UAAU,CAAC,YAAY,EAAE,CAAC;IACrC,CAAC;IAED,6EAA6E;IAC7E,QAAQ;QACJ,OAAO,gBAAgB,EAAE,CAAC;IAC9B,CAAC;IAED,uEAAuE;IACvE,WAAW,CAAC,EAAiC;QACzC,OAAO,WAAW,CAAC,EAAE,CAAC,CAAC;IAC3B,CAAC;IAED,sEAAsE;IACtE,WAAW;QACP,OAAO,eAAe,EAAE,CAAC;IAC7B,CAAC;CACK,CAAC"}
+{"version":3,"file":"updates.js","sourceRoot":"","sources":["../src/updates.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAU3D;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,aAAa,CAAC,MAAqB;IAC/C,UAAU,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;AACjC,CAAC;AAED,MAAM,CAAC,MAAM,OAAO,GAAG;IACnB,2EAA2E;IAC3E,cAAc;QACV,OAAO,UAAU,CAAC,cAAc,EAAE,CAAC;IACvC,CAAC;IAED;;;OAGG;IACH,QAAQ,CAAC,QAAyB;QAC9B,OAAO,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACzC,CAAC;IAED;;;;OAIG;IACH,KAAK;QACD,OAAO,UAAU,CAAC,KAAK,EAAE,CAAC;IAC9B,CAAC;IAED;;;;OAIG;IACH,SAAS;QACL,OAAO,UAAU,CAAC,SAAS,EAAE,CAAC;IAClC,CAAC;IAED,uEAAuE;IACvE,mBAAmB;QACf,OAAO,gBAAgB,EAAE,CAAC;IAC9B,CAAC;IAED,0EAA0E;IAC1E,YAAY;QACR,OAAO,UAAU,CAAC,YAAY,EAAE,CAAC;IACrC,CAAC;IAED,6EAA6E;IAC7E,QAAQ;QACJ,OAAO,gBAAgB,EAAE,CAAC;IAC9B,CAAC;IAED,uEAAuE;IACvE,WAAW,CAAC,EAAiC;QACzC,OAAO,WAAW,CAAC,EAAE,CAAC,CAAC;IAC3B,CAAC;IAED,sEAAsE;IACtE,WAAW;QACP,OAAO,eAAe,EAAE,CAAC;IAC7B,CAAC;CACK,CAAC"}

package/ios/UpdateDownloader.swift

@@ -1,152 +1,152 @@
-import Foundation
-import CryptoKit
-
-/// Streaming bundle downloader: bytes go straight to `tmp/<id>.partial`
-/// with an incremental SHA-256, then atomically move into `updates/<id>/`
-/// once the hash matches. Single-flight — concurrent calls beyond the first
-/// fail fast.
-final class UpdateDownloader: NSObject, URLSessionDataDelegate {
-
-    private static let inFlightLock = NSLock()
-    private static var inFlight = false
-
-    private let partialURL: URL
-    private var output: FileHandle?
-    private var hasher = SHA256()
-    private var receivedBytes: Int64 = 0
-    private var totalBytes: Int64?
-    private var lastProgressAt = Date.distantPast
-    private var result: String? = "Download did not complete"
-    private let done = DispatchSemaphore(value: 0)
-
-    private init(partialURL: URL) {
-        self.partialURL = partialURL
-    }
-
-    /// Synchronous (call off the main thread). Returns nil on success or an
-    /// error message (prefixed with E_* codes the module maps to the bridge).
-    static func download(
-        url: String,
-        expectedSha256: String,
-        updateId: String,
-        headers: [String: String],
-        manifestJson: String,
-    ) -> String? {
-        let store = UpdateStore.shared
-
-        // Already on disk and intact → success without a byte transferred.
-        if FileManager.default.fileExists(atPath: store.bundleFile(updateId).path),
-           store.verifySha256(updateId) {
-            return nil
-        }
-
-        inFlightLock.lock()
-        if inFlight {
-            inFlightLock.unlock()
-            return "E_DOWNLOAD_IN_PROGRESS: another download is running"
-        }
-        inFlight = true
-        inFlightLock.unlock()
-        defer {
-            inFlightLock.lock()
-            inFlight = false
-            inFlightLock.unlock()
-        }
-
-        guard let requestURL = URL(string: url) else {
-            return "Download failed: invalid URL \(url)"
-        }
-
-        let fm = FileManager.default
-        try? fm.createDirectory(at: store.tmpDir, withIntermediateDirectories: true)
-        let partial = store.tmpDir.appendingPathComponent("\(updateId).partial")
-        fm.createFile(atPath: partial.path, contents: nil)
-
-        let downloader = UpdateDownloader(partialURL: partial)
-        guard let handle = try? FileHandle(forWritingTo: partial) else {
-            return "Download failed: cannot open staging file"
-        }
-        downloader.output = handle
-
-        var request = URLRequest(url: requestURL, timeoutInterval: 30)
-        for (key, value) in headers {
-            request.setValue(value, forHTTPHeaderField: key)
-        }
-        let session = URLSession(configuration: .ephemeral, delegate: downloader, delegateQueue: nil)
-        session.dataTask(with: request).resume()
-        downloader.done.wait()
-        session.finishTasksAndInvalidate()
-
-        if let failure = downloader.result {
-            try? fm.removeItem(at: partial)
-            return failure
-        }
-
-        let actual = downloader.hasher.finalize().map { String(format: "%02x", $0) }.joined()
-        guard actual == expectedSha256.lowercased() else {
-            try? fm.removeItem(at: partial)
-            return "E_HASH_MISMATCH: expected \(expectedSha256), got \(actual)"
-        }
-
-        // Promote: metadata first, bundle move last.
-        let dir = store.updateDir(updateId)
-        try? fm.removeItem(at: dir)
-        do {
-            try fm.createDirectory(at: dir, withIntermediateDirectories: true)
-            var meta = (try? JSONSerialization.jsonObject(with: Data(manifestJson.utf8))) as? [String: Any] ?? [:]
-            meta["sha256"] = expectedSha256.lowercased()
-            meta["sizeBytes"] = downloader.receivedBytes
-            meta["sourceUrl"] = url
-            meta["downloadedAt"] = Int(Date().timeIntervalSince1970 * 1000)
-            let metaData = try JSONSerialization.data(withJSONObject: meta)
-            try metaData.write(to: store.updateJsonFile(updateId), options: .atomic)
-            try fm.moveItem(at: partial, to: store.bundleFile(updateId))
-        } catch {
-            try? fm.removeItem(at: partial)
-            return "Download failed: \(error.localizedDescription)"
-        }
-        return nil
-    }
-
-    // MARK: - URLSessionDataDelegate
-
-    func urlSession(
-        _ session: URLSession, dataTask: URLSessionDataTask,
-        didReceive response: URLResponse,
-        completionHandler: @escaping (URLSession.ResponseDisposition) -> Void,
-    ) {
-        if let http = response as? HTTPURLResponse, !(200...299).contains(http.statusCode) {
-            result = "Download failed: HTTP \(http.statusCode)"
-            completionHandler(.cancel)
-            return
-        }
-        totalBytes = response.expectedContentLength >= 0 ? response.expectedContentLength : nil
-        completionHandler(.allow)
-    }
-
-    func urlSession(_ session: URLSession, dataTask: URLSessionDataTask, didReceive data: Data) {
-        output?.write(data)
-        hasher.update(data: data)
-        receivedBytes += Int64(data.count)
-        let now = Date()
-        if now.timeIntervalSince(lastProgressAt) >= 0.15 {
-            lastProgressAt = now
-            UpdatesEventBus.shared.emitProgress(receivedBytes: receivedBytes, totalBytes: totalBytes)
-        }
-    }
-
-    func urlSession(_ session: URLSession, task: URLSessionTask, didCompleteWithError error: Error?) {
-        try? output?.close()
-        if let error {
-            // A cancel from didReceive(response:) already set a specific message.
-            if result == "Download did not complete" || result == nil {
-                result = "Download failed: \(error.localizedDescription)"
-            }
-        } else {
-            result = nil
-            UpdatesEventBus.shared.emitProgress(
-                receivedBytes: receivedBytes, totalBytes: totalBytes ?? receivedBytes)
-        }
-        done.signal()
-    }
-}
+import Foundation
+import CryptoKit
+
+/// Streaming bundle downloader: bytes go straight to `tmp/<id>.partial`
+/// with an incremental SHA-256, then atomically move into `updates/<id>/`
+/// once the hash matches. Single-flight — concurrent calls beyond the first
+/// fail fast.
+final class UpdateDownloader: NSObject, URLSessionDataDelegate {
+
+    private static let inFlightLock = NSLock()
+    private static var inFlight = false
+
+    private let partialURL: URL
+    private var output: FileHandle?
+    private var hasher = SHA256()
+    private var receivedBytes: Int64 = 0
+    private var totalBytes: Int64?
+    private var lastProgressAt = Date.distantPast
+    private var result: String? = "Download did not complete"
+    private let done = DispatchSemaphore(value: 0)
+
+    private init(partialURL: URL) {
+        self.partialURL = partialURL
+    }
+
+    /// Synchronous (call off the main thread). Returns nil on success or an
+    /// error message (prefixed with E_* codes the module maps to the bridge).
+    static func download(
+        url: String,
+        expectedSha256: String,
+        updateId: String,
+        headers: [String: String],
+        manifestJson: String,
+    ) -> String? {
+        let store = UpdateStore.shared
+
+        // Already on disk and intact → success without a byte transferred.
+        if FileManager.default.fileExists(atPath: store.bundleFile(updateId).path),
+           store.verifySha256(updateId) {
+            return nil
+        }
+
+        inFlightLock.lock()
+        if inFlight {
+            inFlightLock.unlock()
+            return "E_DOWNLOAD_IN_PROGRESS: another download is running"
+        }
+        inFlight = true
+        inFlightLock.unlock()
+        defer {
+            inFlightLock.lock()
+            inFlight = false
+            inFlightLock.unlock()
+        }
+
+        guard let requestURL = URL(string: url) else {
+            return "Download failed: invalid URL \(url)"
+        }
+
+        let fm = FileManager.default
+        try? fm.createDirectory(at: store.tmpDir, withIntermediateDirectories: true)
+        let partial = store.tmpDir.appendingPathComponent("\(updateId).partial")
+        fm.createFile(atPath: partial.path, contents: nil)
+
+        let downloader = UpdateDownloader(partialURL: partial)
+        guard let handle = try? FileHandle(forWritingTo: partial) else {
+            return "Download failed: cannot open staging file"
+        }
+        downloader.output = handle
+
+        var request = URLRequest(url: requestURL, timeoutInterval: 30)
+        for (key, value) in headers {
+            request.setValue(value, forHTTPHeaderField: key)
+        }
+        let session = URLSession(configuration: .ephemeral, delegate: downloader, delegateQueue: nil)
+        session.dataTask(with: request).resume()
+        downloader.done.wait()
+        session.finishTasksAndInvalidate()
+
+        if let failure = downloader.result {
+            try? fm.removeItem(at: partial)
+            return failure
+        }
+
+        let actual = downloader.hasher.finalize().map { String(format: "%02x", $0) }.joined()
+        guard actual == expectedSha256.lowercased() else {
+            try? fm.removeItem(at: partial)
+            return "E_HASH_MISMATCH: expected \(expectedSha256), got \(actual)"
+        }
+
+        // Promote: metadata first, bundle move last.
+        let dir = store.updateDir(updateId)
+        try? fm.removeItem(at: dir)
+        do {
+            try fm.createDirectory(at: dir, withIntermediateDirectories: true)
+            var meta = (try? JSONSerialization.jsonObject(with: Data(manifestJson.utf8))) as? [String: Any] ?? [:]
+            meta["sha256"] = expectedSha256.lowercased()
+            meta["sizeBytes"] = downloader.receivedBytes
+            meta["sourceUrl"] = url
+            meta["downloadedAt"] = Int(Date().timeIntervalSince1970 * 1000)
+            let metaData = try JSONSerialization.data(withJSONObject: meta)
+            try metaData.write(to: store.updateJsonFile(updateId), options: .atomic)
+            try fm.moveItem(at: partial, to: store.bundleFile(updateId))
+        } catch {
+            try? fm.removeItem(at: partial)
+            return "Download failed: \(error.localizedDescription)"
+        }
+        return nil
+    }
+
+    // MARK: - URLSessionDataDelegate
+
+    func urlSession(
+        _ session: URLSession, dataTask: URLSessionDataTask,
+        didReceive response: URLResponse,
+        completionHandler: @escaping (URLSession.ResponseDisposition) -> Void,
+    ) {
+        if let http = response as? HTTPURLResponse, !(200...299).contains(http.statusCode) {
+            result = "Download failed: HTTP \(http.statusCode)"
+            completionHandler(.cancel)
+            return
+        }
+        totalBytes = response.expectedContentLength >= 0 ? response.expectedContentLength : nil
+        completionHandler(.allow)
+    }
+
+    func urlSession(_ session: URLSession, dataTask: URLSessionDataTask, didReceive data: Data) {
+        output?.write(data)
+        hasher.update(data: data)
+        receivedBytes += Int64(data.count)
+        let now = Date()
+        if now.timeIntervalSince(lastProgressAt) >= 0.15 {
+            lastProgressAt = now
+            UpdatesEventBus.shared.emitProgress(receivedBytes: receivedBytes, totalBytes: totalBytes)
+        }
+    }
+
+    func urlSession(_ session: URLSession, task: URLSessionTask, didCompleteWithError error: Error?) {
+        try? output?.close()
+        if let error {
+            // A cancel from didReceive(response:) already set a specific message.
+            if result == "Download did not complete" || result == nil {
+                result = "Download failed: \(error.localizedDescription)"
+            }
+        } else {
+            result = nil
+            UpdatesEventBus.shared.emitProgress(
+                receivedBytes: receivedBytes, totalBytes: totalBytes ?? receivedBytes)
+        }
+        done.signal()
+    }
+}