tauri-plugin-hot-update-api 0.1.0

package/README.md

@@ -0,0 +1,58 @@
+# tauri-plugin-hot-update-api
+
+TypeScript bindings for [`tauri-plugin-hot-update`](https://github.com/yanqianglu/tauri-plugin-hot-update)
+— hot update / OTA live updates (CodePush-style, self-hosted) for Tauri v2
+mobile and desktop apps. Ship frontend bundle updates to installed apps
+without a store release, guarded by an automatic anti-brick rollback state
+machine.
+
+Requires the Rust plugin to be installed and configured (manifest URL +
+minisign public keys in `tauri.conf.json`) — see the
+[plugin README](https://github.com/yanqianglu/tauri-plugin-hot-update) for
+setup, signing, and publishing.
+
+## Usage
+
+```ts
+import {
+  check,
+  download,
+  notifyAppReady,
+  currentBundle,
+  onDownloadProgress,
+} from "tauri-plugin-hot-update-api";
+
+// 1. On every launch, as soon as your app shell has rendered:
+//    commits the running bundle as last-known-good. A launch that never
+//    acks is rolled back on the next boot. Safe to call unconditionally.
+await notifyAppReady();
+
+// 2. Whenever the app decides (launch/resume — the plugin never auto-polls):
+const unlisten = await onDownloadProgress(({ downloaded, total }) => {
+  console.log(`OTA download: ${Math.round((downloaded / total) * 100)}%`);
+});
+const outcome = await download();
+unlisten();
+
+if (outcome.status === "staged") {
+  // The update applies on the next cold launch.
+  console.log(`v${outcome.version} ready — restart to apply`);
+}
+
+// Introspection:
+const bundle = await currentBundle();
+// { source: "ota" | "embedded", seq: number | null, version: string }
+```
+
+`check()` fetches and verifies the manifest without downloading, for apps
+that want to ask before pulling the archive.
+
+## Permissions
+
+Grant the plugin's commands in your capability file:
+
+```json
+{ "permissions": ["hot-update:default"] }
+```
+
+Dual-licensed under MIT or Apache-2.0, at your option.

package/dist/index.cjs

@@ -0,0 +1,61 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// index.ts
+var index_exports = {};
+__export(index_exports, {
+  check: () => check,
+  currentBundle: () => currentBundle,
+  download: () => download,
+  notifyAppReady: () => notifyAppReady,
+  onDownloadProgress: () => onDownloadProgress,
+  reset: () => reset
+});
+module.exports = __toCommonJS(index_exports);
+var import_core = require("@tauri-apps/api/core");
+var import_event = require("@tauri-apps/api/event");
+async function check() {
+  return (0, import_core.invoke)("plugin:hot-update|check");
+}
+async function download() {
+  return (0, import_core.invoke)("plugin:hot-update|download");
+}
+async function notifyAppReady() {
+  return (0, import_core.invoke)("plugin:hot-update|notify_app_ready");
+}
+async function currentBundle() {
+  return (0, import_core.invoke)("plugin:hot-update|current_bundle");
+}
+async function reset() {
+  return (0, import_core.invoke)("plugin:hot-update|reset");
+}
+async function onDownloadProgress(handler) {
+  return (0, import_event.listen)("hot-update://progress", (event) => {
+    handler(event.payload);
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  check,
+  currentBundle,
+  download,
+  notifyAppReady,
+  onDownloadProgress,
+  reset
+});

package/dist/index.d.cts

@@ -0,0 +1,153 @@
+import { UnlistenFn } from '@tauri-apps/api/event';
+
+/** Where the bundle archive lives and what it must hash to. */
+interface ArchiveInfo {
+    url: string;
+    /** Hex sha256 of the archive bytes. */
+    sha256: string;
+    /** Exact archive byte count. */
+    size: number;
+}
+/** The signed update manifest, as verified by the plugin. */
+interface Manifest {
+    /** Bundle version; strictly newer than anything this install has seen. */
+    version: string;
+    /** Informational publish timestamp (RFC 3339). */
+    createdAt: string;
+    /** Minimum shell (app) version able to run this bundle. */
+    minShellVersion: string;
+    archive: ArchiveInfo;
+}
+/**
+ * Result of a check or download pass. Refusals are first-class outcomes,
+ * not errors — the pipeline saying "this manifest is not for us", with the
+ * reason preserved:
+ *
+ * - `available` — a verified, applicable update is offered (`check` only).
+ * - `staged` — downloaded, verified, and staged; it becomes active on the
+ *   next cold launch (`download` only).
+ * - `upToDate` — the offered version is not newer than what this install
+ *   has already seen (the everyday "no update" answer).
+ * - `blacklisted` — the offered archive previously failed a trial boot; a
+ *   fixed release must ship under a new hash.
+ * - `shellTooOld` — the bundle needs a newer app binary; a store update is
+ *   required first.
+ * - `alreadyStaged` — exactly this archive is already waiting for its
+ *   trial boot.
+ */
+type UpdateOutcome = {
+    status: "available";
+    manifest: Manifest;
+} | {
+    status: "staged";
+    seq: number;
+    version: string;
+} | {
+    status: "upToDate";
+    offered: string;
+    watermark: string;
+} | {
+    status: "blacklisted";
+    version: string;
+} | {
+    status: "shellTooOld";
+    required: string;
+    shell: string;
+} | {
+    status: "alreadyStaged";
+    seq: number;
+    version: string;
+};
+/** {@link check} never downloads, so it never reports `staged`. */
+type CheckOutcome = Exclude<UpdateOutcome, {
+    status: "staged";
+}>;
+/** {@link download} resolves what happened, never a bare offer. */
+type DownloadOutcome = Exclude<UpdateOutcome, {
+    status: "available";
+}>;
+/**
+ * Result of {@link notifyAppReady}:
+ *
+ * - `committed` — this launch's trial bundle is now the last-known-good.
+ * - `alreadyCommitted` — steady state; the ack is idempotent.
+ * - `embeddedNoop` — serving embedded assets (or the plugin is disabled);
+ *   nothing to commit.
+ * - `stale` — the booted bundle no longer matches on-disk state (e.g. a
+ *   `reset()` ran mid-session); refusing to commit is the safe answer.
+ */
+type AckOutcome = {
+    status: "committed";
+    seq: number;
+} | {
+    status: "alreadyCommitted";
+    seq: number;
+} | {
+    status: "embeddedNoop";
+} | {
+    status: "stale";
+    seq: number;
+};
+/** Where the currently served frontend comes from. */
+type BundleSource = "embedded" | "ota";
+/** Snapshot of what this process is serving. */
+interface CurrentBundle {
+    source: BundleSource;
+    /** Bundle sequence number when `source` is `"ota"`, otherwise null. */
+    seq: number | null;
+    version: string;
+}
+/** Payload of the download progress event (bytes). */
+interface DownloadProgress {
+    downloaded: number;
+    total: number;
+}
+/**
+ * Fetch and verify the signed manifest, then report whether an update
+ * applies. Never downloads the archive. The app owns timing — the plugin
+ * does not auto-poll; call this on launch/resume.
+ *
+ * Rejects on transport or signature-verification failures, and when the
+ * plugin is disabled by config.
+ */
+declare function check(): Promise<CheckOutcome>;
+/**
+ * The full pipeline: check, and if an update applies — download, verify,
+ * extract, and stage it for the next cold launch. Emits throttled
+ * {@link onDownloadProgress} events while the archive streams.
+ *
+ * Concurrent calls are serialized; the loser reports `alreadyStaged` /
+ * `upToDate` instead of downloading twice. Rejects on transport or
+ * verification failures, and when the plugin is disabled by config.
+ */
+declare function download(): Promise<DownloadOutcome>;
+/**
+ * Commit the bundle this launch booted as last-known-good.
+ *
+ * Call once per launch, as soon as the app shell has mounted and rendered —
+ * deliberately independent of network reachability or auth, so a backend
+ * outage can never condemn a good bundle. A launch that never acks is
+ * rolled back and its bundle blacklisted on the next boot.
+ *
+ * Idempotent, and safe to call unconditionally: on embedded assets or with
+ * the plugin disabled it resolves `{ status: "embeddedNoop" }`.
+ */
+declare function notifyAppReady(): Promise<AckOutcome>;
+/** What is being served right now. */
+declare function currentBundle(): Promise<CurrentBundle>;
+/**
+ * Debug/support escape hatch: wipe all OTA state and bundles. The current
+ * session keeps serving what it booted; the next launch reverts to the
+ * embedded assets. A no-op while the plugin is disabled.
+ */
+declare function reset(): Promise<void>;
+/**
+ * Listen to {@link download} progress. Events are throttled plugin-side
+ * (at most ~10/s); the final 100% event (`downloaded === total`) is always
+ * delivered.
+ *
+ * Returns an unlisten function.
+ */
+declare function onDownloadProgress(handler: (progress: DownloadProgress) => void): Promise<UnlistenFn>;
+
+export { type AckOutcome, type ArchiveInfo, type BundleSource, type CheckOutcome, type CurrentBundle, type DownloadOutcome, type DownloadProgress, type Manifest, type UpdateOutcome, check, currentBundle, download, notifyAppReady, onDownloadProgress, reset };

package/dist/index.d.ts

@@ -0,0 +1,153 @@
+import { UnlistenFn } from '@tauri-apps/api/event';
+
+/** Where the bundle archive lives and what it must hash to. */
+interface ArchiveInfo {
+    url: string;
+    /** Hex sha256 of the archive bytes. */
+    sha256: string;
+    /** Exact archive byte count. */
+    size: number;
+}
+/** The signed update manifest, as verified by the plugin. */
+interface Manifest {
+    /** Bundle version; strictly newer than anything this install has seen. */
+    version: string;
+    /** Informational publish timestamp (RFC 3339). */
+    createdAt: string;
+    /** Minimum shell (app) version able to run this bundle. */
+    minShellVersion: string;
+    archive: ArchiveInfo;
+}
+/**
+ * Result of a check or download pass. Refusals are first-class outcomes,
+ * not errors — the pipeline saying "this manifest is not for us", with the
+ * reason preserved:
+ *
+ * - `available` — a verified, applicable update is offered (`check` only).
+ * - `staged` — downloaded, verified, and staged; it becomes active on the
+ *   next cold launch (`download` only).
+ * - `upToDate` — the offered version is not newer than what this install
+ *   has already seen (the everyday "no update" answer).
+ * - `blacklisted` — the offered archive previously failed a trial boot; a
+ *   fixed release must ship under a new hash.
+ * - `shellTooOld` — the bundle needs a newer app binary; a store update is
+ *   required first.
+ * - `alreadyStaged` — exactly this archive is already waiting for its
+ *   trial boot.
+ */
+type UpdateOutcome = {
+    status: "available";
+    manifest: Manifest;
+} | {
+    status: "staged";
+    seq: number;
+    version: string;
+} | {
+    status: "upToDate";
+    offered: string;
+    watermark: string;
+} | {
+    status: "blacklisted";
+    version: string;
+} | {
+    status: "shellTooOld";
+    required: string;
+    shell: string;
+} | {
+    status: "alreadyStaged";
+    seq: number;
+    version: string;
+};
+/** {@link check} never downloads, so it never reports `staged`. */
+type CheckOutcome = Exclude<UpdateOutcome, {
+    status: "staged";
+}>;
+/** {@link download} resolves what happened, never a bare offer. */
+type DownloadOutcome = Exclude<UpdateOutcome, {
+    status: "available";
+}>;
+/**
+ * Result of {@link notifyAppReady}:
+ *
+ * - `committed` — this launch's trial bundle is now the last-known-good.
+ * - `alreadyCommitted` — steady state; the ack is idempotent.
+ * - `embeddedNoop` — serving embedded assets (or the plugin is disabled);
+ *   nothing to commit.
+ * - `stale` — the booted bundle no longer matches on-disk state (e.g. a
+ *   `reset()` ran mid-session); refusing to commit is the safe answer.
+ */
+type AckOutcome = {
+    status: "committed";
+    seq: number;
+} | {
+    status: "alreadyCommitted";
+    seq: number;
+} | {
+    status: "embeddedNoop";
+} | {
+    status: "stale";
+    seq: number;
+};
+/** Where the currently served frontend comes from. */
+type BundleSource = "embedded" | "ota";
+/** Snapshot of what this process is serving. */
+interface CurrentBundle {
+    source: BundleSource;
+    /** Bundle sequence number when `source` is `"ota"`, otherwise null. */
+    seq: number | null;
+    version: string;
+}
+/** Payload of the download progress event (bytes). */
+interface DownloadProgress {
+    downloaded: number;
+    total: number;
+}
+/**
+ * Fetch and verify the signed manifest, then report whether an update
+ * applies. Never downloads the archive. The app owns timing — the plugin
+ * does not auto-poll; call this on launch/resume.
+ *
+ * Rejects on transport or signature-verification failures, and when the
+ * plugin is disabled by config.
+ */
+declare function check(): Promise<CheckOutcome>;
+/**
+ * The full pipeline: check, and if an update applies — download, verify,
+ * extract, and stage it for the next cold launch. Emits throttled
+ * {@link onDownloadProgress} events while the archive streams.
+ *
+ * Concurrent calls are serialized; the loser reports `alreadyStaged` /
+ * `upToDate` instead of downloading twice. Rejects on transport or
+ * verification failures, and when the plugin is disabled by config.
+ */
+declare function download(): Promise<DownloadOutcome>;
+/**
+ * Commit the bundle this launch booted as last-known-good.
+ *
+ * Call once per launch, as soon as the app shell has mounted and rendered —
+ * deliberately independent of network reachability or auth, so a backend
+ * outage can never condemn a good bundle. A launch that never acks is
+ * rolled back and its bundle blacklisted on the next boot.
+ *
+ * Idempotent, and safe to call unconditionally: on embedded assets or with
+ * the plugin disabled it resolves `{ status: "embeddedNoop" }`.
+ */
+declare function notifyAppReady(): Promise<AckOutcome>;
+/** What is being served right now. */
+declare function currentBundle(): Promise<CurrentBundle>;
+/**
+ * Debug/support escape hatch: wipe all OTA state and bundles. The current
+ * session keeps serving what it booted; the next launch reverts to the
+ * embedded assets. A no-op while the plugin is disabled.
+ */
+declare function reset(): Promise<void>;
+/**
+ * Listen to {@link download} progress. Events are throttled plugin-side
+ * (at most ~10/s); the final 100% event (`downloaded === total`) is always
+ * delivered.
+ *
+ * Returns an unlisten function.
+ */
+declare function onDownloadProgress(handler: (progress: DownloadProgress) => void): Promise<UnlistenFn>;
+
+export { type AckOutcome, type ArchiveInfo, type BundleSource, type CheckOutcome, type CurrentBundle, type DownloadOutcome, type DownloadProgress, type Manifest, type UpdateOutcome, check, currentBundle, download, notifyAppReady, onDownloadProgress, reset };

package/dist/index.js

@@ -0,0 +1,31 @@
+// index.ts
+import { invoke } from "@tauri-apps/api/core";
+import { listen } from "@tauri-apps/api/event";
+async function check() {
+  return invoke("plugin:hot-update|check");
+}
+async function download() {
+  return invoke("plugin:hot-update|download");
+}
+async function notifyAppReady() {
+  return invoke("plugin:hot-update|notify_app_ready");
+}
+async function currentBundle() {
+  return invoke("plugin:hot-update|current_bundle");
+}
+async function reset() {
+  return invoke("plugin:hot-update|reset");
+}
+async function onDownloadProgress(handler) {
+  return listen("hot-update://progress", (event) => {
+    handler(event.payload);
+  });
+}
+export {
+  check,
+  currentBundle,
+  download,
+  notifyAppReady,
+  onDownloadProgress,
+  reset
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "tauri-plugin-hot-update-api",
+  "version": "0.1.0",
+  "description": "TypeScript API for tauri-plugin-hot-update — hot update / OTA live updates (CodePush-style, self-hosted) for Tauri v2 mobile and desktop apps",
+  "license": "(MIT OR Apache-2.0)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yanqianglu/tauri-plugin-hot-update.git"
+  },
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup index.ts --format esm,cjs --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@tauri-apps/api": ">=2.0.0"
+  },
+  "devDependencies": {
+    "@tauri-apps/api": "^2.10.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "keywords": [
+    "tauri",
+    "tauri-plugin",
+    "hot-update",
+    "ota",
+    "over-the-air",
+    "live-update",
+    "codepush",
+    "expo-updates",
+    "hotfix",
+    "self-hosted",
+    "ios",
+    "android",
+    "mobile"
+  ]
+}