@capuchoo/updater 0.1.0

package/README.md

@@ -0,0 +1,85 @@
+# @capuchoo/updater
+
+The app-side runtime for [Capuchooo](https://github.com/aybinv7/capuchoo): it asks your update
+server what to do, downloads OTA bundles or native binaries, and drives the install. Built on
+`@capgo/capacitor-updater`.
+
+```sh
+npm install @capuchoo/updater @capuchoo/core
+```
+
+Peers you will already have in a Capacitor app: `@capacitor/core`, `@capacitor/app`,
+`@capacitor/filesystem`, `@capacitor/network`, `@capacitor/file-transfer`,
+`@capawesome-team/capacitor-file-opener`, `@capgo/capacitor-updater`. `vue` is optional and only
+needed for the `/vue` entry point.
+
+## Three things, in order
+
+### 1. Call `notifyAppReady()` first
+
+```ts
+// src/main.ts
+import { notifyAppReady } from "@capuchoo/updater";
+
+void notifyAppReady();
+```
+
+Early, and unconditionally. It confirms that the bundle **currently running** booted. If the plugin
+does not hear it within `appReadyTimeout` (10 s), it concludes the bundle crashed and rolls back to
+the previous one — so gating this call behind a condition, or awaiting a network request before it,
+reverts working updates. It is not a gate on auto-update.
+
+### 2. Configure the plugin through `capuchoUpdaterConfig()`
+
+```ts
+// capacitor.config.ts
+import { capuchoUpdaterConfig } from "@capuchoo/updater/capacitor";
+
+plugins: {
+  CapacitorUpdater: capuchoUpdaterConfig({
+    apiUrl: process.env.VITE_UPDATE_API_URL,
+    channel: process.env.VITE_UPDATE_CHANNEL,
+  }),
+}
+```
+
+This returns `autoUpdate: "onlyDownload"`, because the app drives the install itself — with
+`autoUpdate: true` the plugin and your UI both apply bundles, and a device can download the same
+bundle twice or reload mid-prompt. It also **throws on an empty `apiUrl`** rather than accepting
+one: an empty update URL does not fail at runtime, it silently disables updates, which ships a build
+that never checks.
+
+### 3. Drive it from your UI
+
+```ts
+import { useUpdater } from "@capuchoo/updater/vue";
+
+const updater = useUpdater();
+await updater.init();
+```
+
+`UpdaterState` exposes `checking`, `downloading`, `installing`, `updateAvailable`, `currentUpdate`,
+`progress`, `cachedPath`, `error`, `statusMessage` and `lastCheckMessage`.
+
+Without Vue, use the services directly: `checkForUpdate()`, `downloadNativeUpdate()`,
+`openNativeInstaller()`, `applyOtaUpdate()`, `getCurrentBundle()`, `discardBundle()`.
+
+## Errors are not "up to date"
+
+`checkForUpdate()` throws `UpdateCheckBlockedError` when the server reports a configuration problem
+— an unknown channel, or an environment mismatch between the build and the channel. Show it.
+Treating every non-update response as "nothing to do" is how a broken channel goes unnoticed for
+weeks.
+
+`UpdaterConfigError` means the runtime was never configured — usually a missing `apiUrl`.
+
+## One request decides everything
+
+The runtime asks `POST /api/update` and nothing else. It is the only endpoint that consults the
+channel's assigned native version _and_ an OTA bundle's `min_update_version` gate, and it sends the
+real current bundle version rather than a constant. Native updates outrank OTA, because the server
+can legitimately return both.
+
+## Stability
+
+Pre-1.0: the surface may change between minor versions.

package/dist/capacitor-config.d.ts

@@ -0,0 +1,58 @@
+//#region src/capacitor-config.d.ts
+/**
+ * Builds the `CapacitorUpdater` plugin block for `capacitor.config.ts`.
+ *
+ * This exists because the plugin's `autoUpdate` mode has to agree with how the
+ * app drives updates, and getting it wrong fails in a way that is very hard to
+ * diagnose. The app template shipped `autoUpdate: true` while also calling
+ * `download()` and `set()` from JavaScript: the plugin applied bundles on its
+ * own schedule at the same time as the UI was downloading them, so a device
+ * could download the same bundle twice, or reload mid-prompt.
+ *
+ * `"onlyDownload"` is the mode this package is written for. The plugin fetches
+ * the bundle in the background and raises `updateAvailable`; the app decides
+ * when to apply it. Pass `mode: "manual"` to disable background downloads
+ * entirely and drive everything from `useUpdater`.
+ *
+ * Imported from `capacitor.config.ts`, so it must stay free of any runtime or
+ * DOM dependency.
+ */
+type UpdaterMode = "onlyDownload" | "manual";
+interface UpdaterPluginOptions {
+  /** Base URL of the Capucho backend. No trailing slash needed. */
+  apiUrl: string;
+  /** Channel this build defaults to. */
+  channel: string;
+  /**
+   * Version the plugin reports as the built-in bundle. Pass the app's
+   * package.json version - if this is stale, the server compares against the
+   * wrong baseline and re-serves bundles the device already has.
+   */
+  version: string;
+  mode?: UpdaterMode;
+  /** Milliseconds the plugin waits for `notifyAppReady` before rolling back. */
+  appReadyTimeout?: number;
+  responseTimeout?: number;
+  /**
+   * Whether the app may point the plugin at a different server at runtime.
+   * Leave off in production: it lets anything running in the WebView redirect
+   * update downloads.
+   */
+  allowModifyUrl?: boolean;
+}
+interface CapacitorUpdaterPluginConfig {
+  autoUpdate: boolean | "onlyDownload";
+  updateUrl: string;
+  statsUrl: string;
+  channelUrl: string;
+  defaultChannel: string;
+  version: string;
+  directUpdate: boolean;
+  appReadyTimeout: number;
+  responseTimeout: number;
+  allowModifyUrl: boolean;
+}
+declare function capuchoUpdaterConfig(options: UpdaterPluginOptions): CapacitorUpdaterPluginConfig;
+//#endregion
+export { CapacitorUpdaterPluginConfig, UpdaterMode, UpdaterPluginOptions, capuchoUpdaterConfig };
+//# sourceMappingURL=capacitor-config.d.ts.map

package/dist/capacitor-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capacitor-config.d.ts","names":[],"sources":["../src/capacitor-config.ts"],"mappings":";;;;;;;;;;;;;;;;;;;KAmBY;UAEK;;EAEf;;EAEA;;;;;;EAMA;EACA,OAAO;;EAEP;EACA;;;;;;EAMA;;UAGe;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;iBAGc,qBAAqB,SAAS,uBAAuB"}

package/dist/capacitor-config.js

@@ -0,0 +1,21 @@
+//#region src/capacitor-config.ts
+function capuchoUpdaterConfig(options) {
+	const apiUrl = options.apiUrl.replace(/\/+$/, "");
+	if (!apiUrl) throw new Error("capuchoUpdaterConfig: apiUrl is empty. Set VITE_UPDATE_API_URL for this flavour before building, otherwise the app ships with updates disabled.");
+	return {
+		autoUpdate: (options.mode ?? "onlyDownload") === "onlyDownload" ? "onlyDownload" : false,
+		updateUrl: `${apiUrl}/api/update`,
+		statsUrl: `${apiUrl}/api/stats`,
+		channelUrl: `${apiUrl}/api/channel_self`,
+		defaultChannel: options.channel,
+		version: options.version,
+		directUpdate: false,
+		appReadyTimeout: options.appReadyTimeout ?? 1e4,
+		responseTimeout: options.responseTimeout ?? 3e4,
+		allowModifyUrl: options.allowModifyUrl ?? false
+	};
+}
+//#endregion
+export { capuchoUpdaterConfig };
+
+//# sourceMappingURL=capacitor-config.js.map

package/dist/capacitor-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capacitor-config.js","names":[],"sources":["../src/capacitor-config.ts"],"sourcesContent":["/**\n * Builds the `CapacitorUpdater` plugin block for `capacitor.config.ts`.\n *\n * This exists because the plugin's `autoUpdate` mode has to agree with how the\n * app drives updates, and getting it wrong fails in a way that is very hard to\n * diagnose. The app template shipped `autoUpdate: true` while also calling\n * `download()` and `set()` from JavaScript: the plugin applied bundles on its\n * own schedule at the same time as the UI was downloading them, so a device\n * could download the same bundle twice, or reload mid-prompt.\n *\n * `\"onlyDownload\"` is the mode this package is written for. The plugin fetches\n * the bundle in the background and raises `updateAvailable`; the app decides\n * when to apply it. Pass `mode: \"manual\"` to disable background downloads\n * entirely and drive everything from `useUpdater`.\n *\n * Imported from `capacitor.config.ts`, so it must stay free of any runtime or\n * DOM dependency.\n */\n\nexport type UpdaterMode = \"onlyDownload\" | \"manual\";\n\nexport interface UpdaterPluginOptions {\n  /** Base URL of the Capucho backend. No trailing slash needed. */\n  apiUrl: string;\n  /** Channel this build defaults to. */\n  channel: string;\n  /**\n   * Version the plugin reports as the built-in bundle. Pass the app's\n   * package.json version - if this is stale, the server compares against the\n   * wrong baseline and re-serves bundles the device already has.\n   */\n  version: string;\n  mode?: UpdaterMode;\n  /** Milliseconds the plugin waits for `notifyAppReady` before rolling back. */\n  appReadyTimeout?: number;\n  responseTimeout?: number;\n  /**\n   * Whether the app may point the plugin at a different server at runtime.\n   * Leave off in production: it lets anything running in the WebView redirect\n   * update downloads.\n   */\n  allowModifyUrl?: boolean;\n}\n\nexport interface CapacitorUpdaterPluginConfig {\n  autoUpdate: boolean | \"onlyDownload\";\n  updateUrl: string;\n  statsUrl: string;\n  channelUrl: string;\n  defaultChannel: string;\n  version: string;\n  directUpdate: boolean;\n  appReadyTimeout: number;\n  responseTimeout: number;\n  allowModifyUrl: boolean;\n}\n\nexport function capuchoUpdaterConfig(options: UpdaterPluginOptions): CapacitorUpdaterPluginConfig {\n  const apiUrl = options.apiUrl.replace(/\\/+$/, \"\");\n\n  if (!apiUrl) {\n    // The plugin accepts an empty updateUrl and then silently never checks for\n    // updates, which is the worst possible outcome. Fail the build instead.\n    throw new Error(\n      \"capuchoUpdaterConfig: apiUrl is empty. Set VITE_UPDATE_API_URL for this \" +\n        \"flavour before building, otherwise the app ships with updates disabled.\",\n    );\n  }\n\n  const mode = options.mode ?? \"onlyDownload\";\n\n  return {\n    // \"manual\" means the plugin does nothing on its own.\n    autoUpdate: mode === \"onlyDownload\" ? \"onlyDownload\" : false,\n    updateUrl: `${apiUrl}/api/update`,\n    statsUrl: `${apiUrl}/api/stats`,\n    channelUrl: `${apiUrl}/api/channel_self`,\n    defaultChannel: options.channel,\n    version: options.version,\n    // The app shows a prompt and calls set() itself; letting the plugin apply\n    // the bundle immediately would reload the WebView under the user.\n    directUpdate: false,\n    appReadyTimeout: options.appReadyTimeout ?? 10_000,\n    responseTimeout: options.responseTimeout ?? 30_000,\n    allowModifyUrl: options.allowModifyUrl ?? false,\n  };\n}\n"],"mappings":";AAyDA,SAAgB,qBAAqB,SAA6D;CAChG,MAAM,SAAS,QAAQ,OAAO,QAAQ,QAAQ,EAAE;CAEhD,IAAI,CAAC,QAGH,MAAM,IAAI,MACR,iJAEF;CAKF,OAAO;EAEL,aAJW,QAAQ,QAAQ,oBAIN,iBAAiB,iBAAiB;EACvD,WAAW,GAAG,OAAO;EACrB,UAAU,GAAG,OAAO;EACpB,YAAY,GAAG,OAAO;EACtB,gBAAgB,QAAQ;EACxB,SAAS,QAAQ;EAGjB,cAAc;EACd,iBAAiB,QAAQ,mBAAmB;EAC5C,iBAAiB,QAAQ,mBAAmB;EAC5C,gBAAgB,QAAQ,kBAAkB;CAC5C;AACF"}

package/dist/index.d.ts

@@ -0,0 +1,121 @@
+import { a as DownloadProgress, i as notifyAppReady, n as discardBundle, o as cleanApkCache, r as getCurrentBundle, s as downloadNativeUpdate, t as applyOtaUpdate } from "./ota.service-B3LrcCPr.js";
+import { Environment, Platform, ResolvedUpdate, ResolvedUpdate as ResolvedUpdate$1, UpdateCheckResponse, UpdateCheckResponse as UpdateCheckResponse$1, UpdateEvent, UpdateEvent as UpdateEvent$1, UpdateKind } from "@capuchoo/core";
+//#region src/api.service.d.ts
+/** Raised when the updater is misconfigured, rather than reporting "up to date". */
+declare class UpdaterConfigError extends Error {
+  readonly problems: string[];
+  constructor(problems: string[]);
+}
+/** Raised when the server says the request itself cannot be served. */
+declare class UpdateCheckBlockedError extends Error {
+  readonly response: UpdateCheckResponse$1;
+  constructor(response: UpdateCheckResponse$1);
+}
+/**
+ * Asks the server what this device should be running.
+ *
+ * One request, one endpoint. The app template used to call
+ * `GET /api/native-updates/check` for native updates *and*
+ * `POST /api/update` for OTA, which meant two sources of truth: the native
+ * endpoint ignores the channel's assigned native version and the
+ * `min_update_version` gate, so a device could be told to install an OTA
+ * bundle its binary was too old to run.
+ */
+declare function checkForUpdate(): Promise<ResolvedUpdate$1 | null>;
+/**
+ * Records a native update lifecycle event.
+ *
+ * Best effort: analytics must never break an update. OTA events are reported
+ * by the plugin itself through its `statsUrl`, so only native ones are sent
+ * from here.
+ */
+declare function logUpdateEvent(event: UpdateEvent$1, update: ResolvedUpdate$1, details?: {
+  error?: string;
+}): Promise<void>;
+//#endregion
+//#region src/config.d.ts
+/**
+ * Runtime configuration for the updater.
+ *
+ * Values come from the build's `VITE_*` variables, which the CLI injects from
+ * the flavour's env file. `configureUpdater` lets an app override any of them
+ * at startup - useful for tests and for apps that resolve their endpoint from
+ * a login response rather than at build time.
+ */
+interface UpdaterConfig {
+  /** Base URL of the Capucho backend, with no trailing slash. */
+  apiUrl: string;
+  /** Bundle identifier of this build. Must match what the CLI published. */
+  appId: string;
+  /** Human-readable name, used in prompts and in the APK cache file name. */
+  appName: string;
+  /** Channel to consult. Bound to an environment server-side. */
+  channel: string;
+  /** Free-form: an app may use flavours beyond dev/staging/prod. */
+  environment: string;
+  /** Milliseconds before an update check is abandoned. */
+  timeoutMs: number;
+}
+/**
+ * Overrides configuration resolved from the build. Call before `init`.
+ * Passing `{}` clears previous overrides.
+ */
+declare function configureUpdater(next: Partial<UpdaterConfig>): void;
+declare function getUpdaterConfig(): UpdaterConfig;
+/**
+ * Reasons the updater cannot run, as user-facing strings.
+ *
+ * The previous implementation defaulted `apiUrl` to a hard-coded Render URL and
+ * `appId` to a hard-coded bundle id. A build with a missing variable therefore
+ * silently pointed at somebody else's backend, or asked for the wrong app, and
+ * reported "you are up to date". Failing loudly is the whole point of this
+ * function.
+ */
+declare function describeConfigProblems(config: UpdaterConfig): string[];
+//#endregion
+//#region src/device.d.ts
+/**
+ * Facts about the running build that the server needs in order to decide
+ * whether an update applies.
+ */
+/**
+ * Native build number of the installed binary.
+ *
+ * Returns 0 off-device. The old implementation returned 999999 on web, which
+ * meant a browser session claimed to be newer than every published release and
+ * so never saw an update - masking the very bug you would be debugging.
+ */
+declare function getVersionCode(): Promise<number>;
+/**
+ * Semantic version of the web bundle currently applied.
+ *
+ * `"builtin"` means no OTA bundle has been applied yet and the app is running
+ * the assets compiled into the binary. The server treats it as 0.0.0, so it
+ * must be reported honestly rather than sent as a constant.
+ */
+declare function getBundleVersion(): Promise<string>;
+/**
+ * Stable per-install identifier, supplied by the OTA plugin.
+ *
+ * The plugin persists this natively. Reading `localStorage.device_id` instead -
+ * as the app template did - returns null on a fresh install and is wiped
+ * whenever the WebView data is cleared, so channel overrides and per-device
+ * stats silently stopped working.
+ */
+declare function getDeviceId(): Promise<string>;
+declare function getPlatform(): "android" | "ios" | "web";
+declare function isNative(): boolean;
+//#endregion
+//#region src/install.service.d.ts
+/**
+ * Hands a downloaded APK to the Android package installer.
+ *
+ * Requires `REQUEST_INSTALL_PACKAGES` in the manifest - the Trapeze config for
+ * each flavour merges it in - and the user must have allowed this app to
+ * install unknown apps. Both failures surface as opaque platform errors, so
+ * they are translated into something a user can act on.
+ */
+declare function openNativeInstaller(path: string): Promise<void>;
+//#endregion
+export { type DownloadProgress, type Environment, type Platform, type ResolvedUpdate, UpdateCheckBlockedError, type UpdateCheckResponse, type UpdateEvent, type UpdateKind, type UpdaterConfig, UpdaterConfigError, applyOtaUpdate, checkForUpdate, cleanApkCache, configureUpdater, describeConfigProblems, discardBundle, downloadNativeUpdate, getBundleVersion, getCurrentBundle, getDeviceId, getPlatform, getUpdaterConfig, getVersionCode, isNative, logUpdateEvent, notifyAppReady, openNativeInstaller };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/api.service.ts","../src/config.ts","../src/device.ts","../src/install.service.ts"],"mappings":";;;;cAaa,2BAA2B;WAC7B;EAEG,YAAA;;;cAQD,gCAAgC;WAClC,UAAU;EAEP,YAAA,UAAU;;;;;;;;;;;;iBAuCF,kBAAkB,QAAQ;;;;;;;;iBA8C1B,eACpB,OAAO,eACP,QAAQ,kBACR;EAAY;IACX;;;;;;;;;;;UC5Gc;;EAEf;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;iBAoBc,iBAAiB,MAAM,QAAQ;iBAS/B,oBAAoB;;;;;;;;;;iBAuBpB,uBAAuB,QAAQ;;;;;;;;;;;;;;iBCxDzB,kBAAkB;;;;;;;;iBAkBlB,oBAAoB;;;;;;;;;iBAmBpB,eAAe;iBAWrB;iBAIA;;;;;;;;;;;iBCtDM,oBAAoB,eAAe"}

package/dist/index.js

@@ -0,0 +1,2 @@
+import { _ as configureUpdater, a as openNativeInstaller, c as UpdateCheckBlockedError, d as logUpdateEvent, f as getBundleVersion, g as isNative, h as getVersionCode, i as notifyAppReady, l as UpdaterConfigError, m as getPlatform, n as discardBundle, o as cleanApkCache, p as getDeviceId, r as getCurrentBundle, s as downloadNativeUpdate, t as applyOtaUpdate, u as checkForUpdate, v as describeConfigProblems, y as getUpdaterConfig } from "./ota.service-t2_hIxcy.js";
+export { UpdateCheckBlockedError, UpdaterConfigError, applyOtaUpdate, checkForUpdate, cleanApkCache, configureUpdater, describeConfigProblems, discardBundle, downloadNativeUpdate, getBundleVersion, getCurrentBundle, getDeviceId, getPlatform, getUpdaterConfig, getVersionCode, isNative, logUpdateEvent, notifyAppReady, openNativeInstaller };

package/dist/ota.service-B3LrcCPr.d.ts

@@ -0,0 +1,49 @@
+import { ResolvedUpdate } from "@capuchoo/core";
+//#region src/download.service.d.ts
+interface DownloadProgress {
+  loaded: number;
+  total: number;
+  percent: number;
+}
+/**
+ * Downloads a native APK into the app cache and returns its path.
+ *
+ * The file name embeds the app id, so a staging build and a production build
+ * installed side by side cannot overwrite each other's download. The previous
+ * implementation prefixed every file with a hard-coded app name.
+ */
+declare function downloadNativeUpdate(update: ResolvedUpdate, onProgress: (progress: DownloadProgress) => void): Promise<string>;
+/** Removes this app's cached APKs. Failures are non-fatal. */
+declare function cleanApkCache(): Promise<void>;
+//#endregion
+//#region src/ota.service.d.ts
+/**
+ * Thin wrapper over the OTA plugin.
+ *
+ * Downloading and applying a web bundle stays with `@capgo/capacitor-updater`:
+ * it owns the native bundle store, the atomic swap and the rollback. This
+ * module only sequences those calls correctly.
+ */
+/**
+ * Confirms the current bundle booted successfully.
+ *
+ * **This must be called once, early, on every app start.** If the plugin does
+ * not hear it within `appReadyTimeout`, it assumes the new bundle crashed and
+ * rolls back to the previous one - which looks exactly like "the update did
+ * not install".
+ */
+declare function notifyAppReady(): Promise<void>;
+/** The bundle currently applied, or null off-device. */
+declare function getCurrentBundle(): Promise<import("@capgo/capacitor-updater").CurrentBundleResult | null>;
+/**
+ * Downloads an OTA bundle and applies it.
+ *
+ * `set` swaps the active bundle and reloads the WebView, so nothing after it
+ * runs. It is called last on purpose.
+ */
+declare function applyOtaUpdate(update: ResolvedUpdate): Promise<void>;
+/** Discards a downloaded bundle that will not be applied. */
+declare function discardBundle(bundleId: string): Promise<void>;
+//#endregion
+export { DownloadProgress as a, notifyAppReady as i, discardBundle as n, cleanApkCache as o, getCurrentBundle as r, downloadNativeUpdate as s, applyOtaUpdate as t };
+//# sourceMappingURL=ota.service-B3LrcCPr.d.ts.map

package/dist/ota.service-B3LrcCPr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ota.service-B3LrcCPr.d.ts","names":[],"sources":["../src/download.service.ts","../src/ota.service.ts"],"mappings":";;UAOiB;EACf;EACA;EACA;;;;;;;;;iBAqBoB,qBACpB,QAAQ,gBACR,aAAa,UAAU,4BACtB;;iBAgDmB,iBAAiB;;;;;;;;;;;;;;;;;;iBC9DjB,kBAAkB;;iBAWlB,oBAAgB,2CAAA;;;;;;;iBAiBhB,eAAe,QAAQ,iBAAiB;;iBA4BxC,cAAc,mBAAmB"}