@hot-updater/protocol 1.0.0-rc.20 → 1.0.0-rc.21

package/README.md

@@ -0,0 +1,50 @@
+# @hot-updater/protocol
+
+The device-safe, zero-dependency package for what crosses a boundary:
+
+- the data formats and pure computations that the app and the server share,
+  where both sides must get the same answer;
+- the contracts between a host and its extensions on the device, such as the
+  client plugin contract, and the reference host that runs them.
+
+It runs anywhere: Hermes, Node, Workers, and Deno. Code that only the server
+or the CLI uses belongs in `@hot-updater/plugin-core` or
+`@hot-updater/server`.
+
+## What belongs here
+
+Code moves into this package only when all three hold:
+
+1. It crosses a boundary: a format or computation both the app and the server
+   run, or a contract a host on the device offers its extensions.
+2. It does no I/O of its own: what reaches the device or the network, such as
+   the plugin host's `fetch` and storage, the caller passes in. It uses no Node
+   or React Native API and keeps no global state.
+3. It needs no dependency. This package has none; what it takes from another
+   package, such as verkit's version parsing, is bundled into `dist`.
+
+It holds the domain types, the release catalog format and its scope rules,
+the check a client runs on a fetched release catalog (`parseReleaseCatalog`),
+the rollout cohort math, bundle artifacts, the bundle id format (`uuid`), the
+client plugin contract, `canonicalizeAppVersion`, and `resolveBaseURL`. The
+device's update client and doctor's server checks both run
+`parseReleaseCatalog`, so they accept the same catalogs. Client
+plugin authors import `defineClientPlugin` and its types from here.
+`createPluginHost` is the host the SDK runs client plugins on: a device SDK
+passes it the platform, the device's storage, and `fetch`, and
+`@hot-updater/test-utils/react-native` passes it fakes.
+
+## Boundary with `@hot-updater/plugin-core`
+
+`@hot-updater/plugin-core` is the kit that extends the server: the storage and
+database adapter contracts, the server plugin authoring API, and their
+helpers. It runs wherever the server runs, in Node, Workers, Deno, or Lambda,
+and depends on this package, never the reverse. The app never imports it:
+React Native imports this package and the built-in Insights client, never
+plugin-core or the server.
+
+`src/package.spec.ts` checks that this package has no dependencies and imports
+only what its build bundles. An oxlint rule refuses `@hot-updater/plugin-core`
+and `@hot-updater/server` imports in `packages/protocol/src`,
+`packages/react-native/src`, and the Insights client in
+`plugins/insights/src/client`.

package/dist/index.cjs

@@ -1,4 +1,130 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region ../../node_modules/.pnpm/verkit@0.4.0/node_modules/verkit/dist/comparison-DenM3wCn.js
+const LETTER_DASH_NUMBER = "[a-zA-Z0-9-]";
+const NUMERIC_IDENTIFIER = String.raw`0|[1-9]\d*`;
+const NUMERIC_IDENTIFIER_LOOSE = String.raw`\d+`;
+const NON_NUMERIC_IDENTIFIER = String.raw`\d*[a-zA-Z-]${LETTER_DASH_NUMBER}*`;
+const MAIN_VERSION = String.raw`(${NUMERIC_IDENTIFIER})\.(${NUMERIC_IDENTIFIER})\.(${NUMERIC_IDENTIFIER})`;
+const MAIN_VERSION_LOOSE = String.raw`(${NUMERIC_IDENTIFIER_LOOSE})\.(${NUMERIC_IDENTIFIER_LOOSE})\.(${NUMERIC_IDENTIFIER_LOOSE})`;
+const PRERELEASE_IDENTIFIER = `(?:${NON_NUMERIC_IDENTIFIER}|${NUMERIC_IDENTIFIER})`;
+const PRERELEASE_IDENTIFIER_LOOSE = `(?:${NON_NUMERIC_IDENTIFIER}|${NUMERIC_IDENTIFIER_LOOSE})`;
+const PRERELEASE = String.raw`(?:-(${PRERELEASE_IDENTIFIER}(?:\.${PRERELEASE_IDENTIFIER})*))`;
+const PRERELEASE_LOOSE = String.raw`(?:-?(${PRERELEASE_IDENTIFIER_LOOSE}(?:\.${PRERELEASE_IDENTIFIER_LOOSE})*))`;
+const BUILD_IDENTIFIER = `${LETTER_DASH_NUMBER}+`;
+const BUILD = String.raw`(?:\+(${BUILD_IDENTIFIER}(?:\.${BUILD_IDENTIFIER})*))`;
+const FULL_PLAIN = `v?${MAIN_VERSION}${PRERELEASE}?${BUILD}?`;
+const LOOSE_PLAIN = String.raw`[v=\s]*${MAIN_VERSION_LOOSE}${PRERELEASE_LOOSE}?${BUILD}?`;
+const XRANGE_IDENTIFIER = String.raw`${NUMERIC_IDENTIFIER}|x|X|\*`;
+const XRANGE_IDENTIFIER_LOOSE = String.raw`${NUMERIC_IDENTIFIER_LOOSE}|x|X|\*`;
+String.raw`[v=\s]*(${XRANGE_IDENTIFIER})(?:\.(${XRANGE_IDENTIFIER})(?:\.(${XRANGE_IDENTIFIER})(?:${PRERELEASE})?${BUILD}?)?)?`;
+String.raw`[v=\s]*(${XRANGE_IDENTIFIER_LOOSE})(?:\.(${XRANGE_IDENTIFIER_LOOSE})(?:\.(${XRANGE_IDENTIFIER_LOOSE})(?:${PRERELEASE_LOOSE})?${BUILD}?)?)?`;
+String.raw`(?:\^)`;
+const COERCE_PLAIN = String.raw`(^|[^\d])(\d{1,${16}})(?:\.(\d{1,${16}}))?(?:\.(\d{1,${16}}))?`;
+const COERCE = String.raw`${COERCE_PLAIN}(?:$|[^\d])`;
+const COERCE_FULL = String.raw`${COERCE_PLAIN}(?:${PRERELEASE})?(?:${BUILD})?(?:$|[^\d])`;
+function makeSafeRegexSource(source) {
+	const replacements = [
+		[String.raw`\s`, 1],
+		[String.raw`\d`, 256],
+		[LETTER_DASH_NUMBER, 250]
+	];
+	for (const [token, maximum] of replacements) source = source.split(`${token}*`).join(`${token}{0,${maximum}}`).split(`${token}+`).join(`${token}{1,${maximum}}`);
+	return source;
+}
+function safeRegex(source, flags) {
+	return new RegExp(makeSafeRegexSource(source), flags);
+}
+const FULL = safeRegex(`^${FULL_PLAIN}$`);
+const LOOSE = safeRegex(`^${LOOSE_PLAIN}$`);
+const NUMERIC$1 = /^\d+$/;
+function formatComparableVersion(version) {
+	const base = `${version.major}.${version.minor}.${version.patch}`;
+	return version.prerelease?.length ? `${base}-${version.prerelease.join(".")}` : base;
+}
+function formatFullVersion(version) {
+	const comparable = formatComparableVersion(version);
+	return version.build?.length ? `${comparable}+${version.build.join(".")}` : comparable;
+}
+function parse(version, options = {}) {
+	if (typeof version !== "string") return version;
+	if (version.length > 256) throw new TypeError(`Version exceeds the maximum length of 256 characters`);
+	const match = version.trim().match(options.loose ? LOOSE : FULL);
+	if (!match) throw new TypeError(`Invalid version syntax: ${version}`);
+	const major = Number(match[1]);
+	const minor = Number(match[2]);
+	const patch = Number(match[3]);
+	if (major > Number.MAX_SAFE_INTEGER || major < 0) throw new TypeError(`Invalid major version: ${match[1]}`);
+	if (minor > Number.MAX_SAFE_INTEGER || minor < 0) throw new TypeError(`Invalid minor version: ${match[2]}`);
+	if (patch > Number.MAX_SAFE_INTEGER || patch < 0) throw new TypeError(`Invalid patch version: ${match[3]}`);
+	const prerelease = match[4] ? match[4].split(".").map((identifier) => {
+		if (NUMERIC$1.test(identifier)) {
+			const numeric = Number(identifier);
+			if (numeric >= 0 && numeric < Number.MAX_SAFE_INTEGER) return numeric;
+		}
+		return identifier;
+	}) : void 0;
+	return {
+		build: match[5]?.split("."),
+		major,
+		minor,
+		patch,
+		prerelease
+	};
+}
+function tryParse(version, options = {}) {
+	try {
+		return parse(version, options);
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region ../../node_modules/.pnpm/verkit@0.4.0/node_modules/verkit/dist/version-CQ98ZBpL.js
+const COERCE_EXACT = safeRegex(COERCE);
+const COERCE_FULL_EXACT = safeRegex(COERCE_FULL);
+safeRegex(`^${PRERELEASE}$`);
+safeRegex(`^${PRERELEASE_LOOSE}$`);
+function normalizeFull(version, options = {}) {
+	const parsed = tryParse(version, options);
+	return parsed ? formatFullVersion(parsed) : null;
+}
+function coerce(value, options = {}) {
+	if (typeof value === "object") return value;
+	const input = typeof value === "number" ? String(value) : value;
+	let match = null;
+	if (options.rtl) {
+		const expression = safeRegex(options.includePrerelease ? COERCE_FULL : COERCE, "g");
+		let next;
+		while ((next = expression.exec(input)) && (!match || match.index + match[0].length !== input.length)) {
+			if (!match || next.index + next[0].length !== match.index + match[0].length) match = next;
+			expression.lastIndex = next.index + next[1].length + next[2].length;
+		}
+	} else match = (options.includePrerelease ? COERCE_FULL_EXACT : COERCE_EXACT).exec(input);
+	if (!match) return null;
+	const major = match[2];
+	return tryParse(`${major}.${match[3] || "0"}.${match[4] || "0"}${options.includePrerelease && match[5] ? `-${match[5]}` : ""}${options.includePrerelease && match[6] ? `+${match[6]}` : ""}`, options);
+}
+//#endregion
+//#region src/appVersion.ts
+/**
+* The form of an app version that the device and the server compare:
+* `major.minor.patch` of the first version in `appVersion`, such as `1.4.0`
+* for `v1.4`, or null when it holds none. Prerelease and build parts are
+* dropped.
+*/
+function canonicalizeAppVersion(appVersion) {
+	const version = coerce(appVersion);
+	return version ? normalizeFull(version) : null;
+}
+//#endregion
+//#region src/baseURL.ts
+/** Resolves a functional baseURL and drops trailing slashes. */
+const resolveBaseURL = async (baseURL) => {
+	const resolvedBaseURL = typeof baseURL === "function" ? await baseURL() : baseURL;
+	if (!resolvedBaseURL) throw new Error("baseURL function must return a non-empty string");
+	return resolvedBaseURL.replace(/\/+$/, "");
+};
+//#endregion
 //#region src/bundleArtifacts.ts
 const stripBundleArtifactMetadata = (metadata) => metadata;
 const getManifestStorageUri = (bundle) => bundle.manifestStorageUri;
@@ -37,6 +163,164 @@ const getPatchStorageUri = (bundle) => getPrimaryPatch(bundle)?.patchStorageUri
 /** Declares a client plugin; built-in and third-party plugins use the same contract. */
 const defineClientPlugin = (plugin) => plugin;
 //#endregion
+//#region src/createPluginHost.ts
+/** Storage values stay small, since native reads them on the JS thread. */
+const MAX_STORAGE_VALUE_LENGTH = 65536;
+/** Where a plugin's key lives in native storage. */
+const pluginStorageKey = (pluginId, key) => `plugins/${encodeURIComponent(pluginId)}/${key}`;
+const createPluginHost = (environment) => {
+	let config = null;
+	/** Hooks by plugin, so a plugin configured again is not set up twice. */
+	const setUpPlugins = /* @__PURE__ */ new WeakMap();
+	let activePlugins = [];
+	/** What plugins read and wrote, so a read follows a write before native does. */
+	const storageValues = /* @__PURE__ */ new Map();
+	const reportHookError = (message, error) => {
+		const report = new Error(`[HotUpdater] ${message}`, { cause: error });
+		try {
+			if (config?.onError) {
+				config.onError(report);
+				return;
+			}
+		} catch {}
+		console.warn(report.message, error);
+	};
+	const fetchFromServer = async (path, init = {}) => {
+		if (config === null) throw new Error("[HotUpdater] Plugins can fetch only after init or wrap.");
+		if (/^[a-z][a-z\d+.-]*:/i.test(path) || path.startsWith("//")) throw new TypeError("[HotUpdater] Plugin fetch takes a path relative to baseURL.");
+		const { requestHeaders, requestTimeout } = config;
+		const url = `${await resolveBaseURL(config.baseURL)}/${path.replace(/^\/+/, "")}`;
+		const headers = new Headers(requestHeaders);
+		new Headers(init.headers).forEach((value, name) => {
+			headers.set(name, value);
+		});
+		const controller = new AbortController();
+		const callerSignal = init.signal;
+		const abortFromCaller = () => controller.abort();
+		if (callerSignal?.aborted) controller.abort();
+		callerSignal?.addEventListener("abort", abortFromCaller);
+		const timeoutId = setTimeout(() => controller.abort(), requestTimeout ?? 5e3);
+		try {
+			return await environment.fetch(url, {
+				...init,
+				headers,
+				signal: controller.signal
+			});
+		} catch (error) {
+			if (error instanceof Error && error.name === "AbortError" && !callerSignal?.aborted) throw new Error("Request timed out");
+			throw error;
+		} finally {
+			clearTimeout(timeoutId);
+			callerSignal?.removeEventListener("abort", abortFromCaller);
+		}
+	};
+	const createStorage = (pluginId) => {
+		const scopedKey = (key) => {
+			if (typeof key !== "string" || key.length === 0) throw new TypeError("[HotUpdater] Plugin storage keys are non-empty strings.");
+			return pluginStorageKey(pluginId, key);
+		};
+		return {
+			get: (key) => {
+				const storageKey = scopedKey(key);
+				const cached = storageValues.get(storageKey);
+				if (cached !== void 0) return cached;
+				const value = environment.getStorageItem(storageKey);
+				storageValues.set(storageKey, value);
+				return value;
+			},
+			set: (key, value) => {
+				const storageKey = scopedKey(key);
+				if (value !== null && typeof value !== "string") throw new TypeError("[HotUpdater] Plugin storage values are strings or null.");
+				if (value !== null && value.length > MAX_STORAGE_VALUE_LENGTH) throw new RangeError("[HotUpdater] Plugin storage values are at most 64 KB.");
+				environment.setStorageItem(storageKey, value);
+				storageValues.set(storageKey, value);
+			}
+		};
+	};
+	const createContext = (pluginId) => ({
+		fetch: fetchFromServer,
+		get installId() {
+			return environment.getInstallId();
+		},
+		platform: environment.platform,
+		get appVersion() {
+			return environment.getAppVersion();
+		},
+		get sdkVersion() {
+			return environment.sdkVersion;
+		},
+		isDebugBuild: environment.isDebugBuild,
+		getBundleId: () => environment.getBundleId(),
+		getChannel: () => environment.getChannel(),
+		getCohort: () => environment.getCohort(),
+		getFingerprintHash: () => environment.getFingerprintHash(),
+		storage: createStorage(pluginId),
+		now: () => environment.now()
+	});
+	const configurePlugins = (plugins, nextConfig) => {
+		const ids = /* @__PURE__ */ new Set();
+		for (const plugin of plugins ?? []) {
+			if (typeof plugin.id !== "string" || plugin.id.length === 0) throw new Error("[HotUpdater] A plugin id must be a non-empty string.");
+			if (ids.has(plugin.id)) throw new Error(`[HotUpdater] Two plugins use the id "${plugin.id}". Plugin ids must be unique.`);
+			ids.add(plugin.id);
+		}
+		config = nextConfig;
+		activePlugins = (plugins ?? []).map((plugin) => {
+			let hooks = setUpPlugins.get(plugin);
+			if (hooks === void 0) {
+				try {
+					hooks = plugin.setup(createContext(plugin.id)) ?? {};
+				} catch (error) {
+					reportHookError(`Plugin "${plugin.id}" failed in setup`, error);
+					hooks = {};
+				}
+				setUpPlugins.set(plugin, hooks);
+			}
+			return {
+				plugin,
+				hooks
+			};
+		});
+	};
+	const hasPluginHook = (name) => activePlugins.some(({ hooks }) => typeof hooks[name] === "function");
+	const buildPluginEvent = (name, createPayload) => {
+		if (!hasPluginHook(name)) return null;
+		try {
+			return createPayload();
+		} catch (error) {
+			reportHookError(`Failed to build the ${name} event for plugins`, error);
+			return null;
+		}
+	};
+	const dispatchPluginHook = (name, payload) => {
+		const settlements = [];
+		for (const { plugin, hooks } of activePlugins) {
+			const hook = hooks[name];
+			if (typeof hook !== "function") continue;
+			try {
+				const result = hook.call(hooks, payload);
+				if (result !== null && typeof result === "object" && typeof result.then === "function") settlements.push(Promise.resolve(result).then(() => void 0, (error) => {
+					reportHookError(`Plugin "${plugin.id}" failed in ${name}`, error);
+				}));
+			} catch (error) {
+				reportHookError(`Plugin "${plugin.id}" failed in ${name}`, error);
+			}
+		}
+		return settlements;
+	};
+	const emitPluginHook = (name, createPayload) => {
+		const payload = buildPluginEvent(name, createPayload);
+		if (payload !== null) dispatchPluginHook(name, payload);
+	};
+	return {
+		configurePlugins,
+		hasPluginHook,
+		buildPluginEvent,
+		dispatchPluginHook,
+		emitPluginHook
+	};
+};
+//#endregion
 //#region src/rollout.ts
 const NUMERIC_COHORT_SIZE = 1e3;
 const DEFAULT_ROLLOUT_COHORT_COUNT = NUMERIC_COHORT_SIZE;
@@ -408,14 +692,65 @@ function parseReleaseCatalogScopeKey(scopeKey) {
 	return input;
 }
 //#endregion
-//#region src/types.ts
-const ARTIFACT_PROTOCOL_VERSION = 1;
-//#endregion
 //#region src/uuid.ts
 const NIL_UUID = "00000000-0000-0000-0000-000000000000";
 const UUID_V7_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
 const isUUIDv7 = (value) => typeof value === "string" && UUID_V7_PATTERN.test(value);
 //#endregion
+//#region src/releaseCatalogWire.ts
+/** The largest release catalog response body a client accepts, in UTF-8 bytes. */
+const MAX_RELEASE_CATALOG_WIRE_BYTES = 528384;
+/** The length of `value` in UTF-8 bytes, without an encoder the device may lack. */
+const getUtf8ByteLength = (value) => {
+	let bytes = 0;
+	for (let index = 0; index < value.length; index += 1) {
+		const code = value.charCodeAt(index);
+		if (code <= 127) bytes += 1;
+		else if (code <= 2047) bytes += 2;
+		else if (code >= 55296 && code <= 56319 && index + 1 < value.length && value.charCodeAt(index + 1) >= 56320 && value.charCodeAt(index + 1) <= 57343) {
+			bytes += 4;
+			index += 1;
+		} else bytes += 3;
+	}
+	return bytes;
+};
+const isStringArray = (value) => Array.isArray(value) && value.every((entry) => typeof entry === "string");
+const isValidReleaseDescriptor = (value) => {
+	if (value === null || typeof value !== "object") return false;
+	const descriptor = value;
+	return isUUIDv7(descriptor.releaseId) && (descriptor.kind === "BUNDLE" || descriptor.kind === "EMBEDDED") && (descriptor.kind === "BUNDLE" && typeof descriptor.bundleId === "string" || descriptor.kind === "EMBEDDED" && descriptor.bundleId === null) && Number.isSafeInteger(descriptor.rolloutCohortCount) && descriptor.rolloutCohortCount >= 0 && descriptor.rolloutCohortCount <= 1e3 && isStringArray(descriptor.targetCohorts) && descriptor.targetCohorts.length <= 100 && typeof descriptor.shouldForceUpdate === "boolean" && (descriptor.message === null || typeof descriptor.message === "string");
+};
+/** Whether the catalog is the expected scope's. */
+const hasExpectedReleaseCatalogScope = (catalog, expected) => {
+	try {
+		const parsed = parseReleaseCatalogScopeKey(catalog.scopeKey);
+		return parsed.channelKey === expected.channelKey && parsed.platform === expected.platform && parsed.strategy === expected.strategy && (parsed.strategy === "APP_VERSION" || expected.strategy === "FINGERPRINT" && parsed.fingerprintHash === expected.fingerprintHash);
+	} catch {
+		return false;
+	}
+};
+/**
+* Parses a release catalog response body as a client accepts it: within the
+* wire limit, in the schema's shape, for the expected scope, and within the
+* cohort limits. Any other body is null. The device's update client and
+* doctor's server checks both run this, so they accept the same catalogs.
+*/
+const parseReleaseCatalog = (body, expectedScope) => {
+	if (getUtf8ByteLength(body) > MAX_RELEASE_CATALOG_WIRE_BYTES) return null;
+	try {
+		const catalog = JSON.parse(body);
+		if (catalog.schemaVersion !== 1 || typeof catalog.catalogId !== "string" || catalog.catalogId.length === 0 || typeof catalog.scopeKey !== "string" || !Number.isSafeInteger(catalog.generation) || (catalog.generation ?? 0) < 1 || typeof catalog.catalogHash !== "string" || !/^sha256:[0-9a-f]{64}$/.test(catalog.catalogHash) || catalog.fallbackPolicy !== "BUILTIN_IF_ACTIVE_INELIGIBLE" || !Array.isArray(catalog.releases) || !catalog.releases.every(isValidReleaseDescriptor) || catalog.rollbackReleases !== void 0 && (!Array.isArray(catalog.rollbackReleases) || !catalog.rollbackReleases.every(isValidReleaseDescriptor))) return null;
+		if (!hasExpectedReleaseCatalogScope(catalog, expectedScope)) return null;
+		if (new Set([...catalog.releases, ...catalog.rollbackReleases ?? []].flatMap((release) => release.targetCohorts)).size > 512) return null;
+		return catalog;
+	} catch {
+		return null;
+	}
+};
+//#endregion
+//#region src/types.ts
+const ARTIFACT_PROTOCOL_VERSION = 1;
+//#endregion
 exports.ARTIFACT_PROTOCOL_VERSION = ARTIFACT_PROTOCOL_VERSION;
 exports.DEFAULT_ROLLOUT_COHORT_COUNT = DEFAULT_ROLLOUT_COHORT_COUNT;
 exports.INVALID_COHORT_ERROR_MESSAGE = INVALID_COHORT_ERROR_MESSAGE;
@@ -423,6 +758,7 @@ exports.MAX_COHORT_LENGTH = MAX_COHORT_LENGTH;
 exports.MAX_COMPILED_CATALOG_BYTES = MAX_COMPILED_CATALOG_BYTES;
 exports.MAX_CRASHED_BUNDLES = MAX_CRASHED_BUNDLES;
 exports.MAX_DISTINCT_TARGET_COHORTS_PER_SCOPE = MAX_DISTINCT_TARGET_COHORTS_PER_SCOPE;
+exports.MAX_RELEASE_CATALOG_WIRE_BYTES = MAX_RELEASE_CATALOG_WIRE_BYTES;
 exports.MAX_TARGET_COHORTS_PER_RELEASE = MAX_TARGET_COHORTS_PER_RELEASE;
 exports.NIL_UUID = NIL_UUID;
 exports.NUMERIC_COHORT_SIZE = NUMERIC_COHORT_SIZE;
@@ -431,6 +767,8 @@ exports.RELEASE_CATALOG_SCHEMA_VERSION = RELEASE_CATALOG_SCHEMA_VERSION;
 exports.assertCanonicalChannelName = assertCanonicalChannelName;
 exports.assessCatalogAcceptance = assessCatalogAcceptance;
 exports.authorizeReleaseTransition = authorizeReleaseTransition;
+exports.canonicalizeAppVersion = canonicalizeAppVersion;
+exports.createPluginHost = createPluginHost;
 exports.createReleaseCatalogScopeKey = createReleaseCatalogScopeKey;
 exports.createReleaseSelectionContextHash = createReleaseSelectionContextHash;
 exports.decodeChannelKey = decodeChannelKey;
@@ -449,6 +787,8 @@ exports.getPatchBaseFileHash = getPatchBaseFileHash;
 exports.getPatchFileHash = getPatchFileHash;
 exports.getPatchStorageUri = getPatchStorageUri;
 exports.getRolledOutNumericCohorts = getRolledOutNumericCohorts;
+exports.getUtf8ByteLength = getUtf8ByteLength;
+exports.hasExpectedReleaseCatalogScope = hasExpectedReleaseCatalogScope;
 exports.isCohortEligibleForUpdate = isCohortEligibleForUpdate;
 exports.isCustomCohort = isCustomCohort;
 exports.isNumericCohort = isNumericCohort;
@@ -458,6 +798,9 @@ exports.isValidCohort = isValidCohort;
 exports.normalizeChannelName = normalizeChannelName;
 exports.normalizeCohortValue = normalizeCohortValue;
 exports.normalizeRolloutCohortCount = normalizeRolloutCohortCount;
+exports.parseReleaseCatalog = parseReleaseCatalog;
 exports.parseReleaseCatalogScopeKey = parseReleaseCatalogScopeKey;
+exports.pluginStorageKey = pluginStorageKey;
+exports.resolveBaseURL = resolveBaseURL;
 exports.selectDesiredRelease = selectDesiredRelease;
 exports.stripBundleArtifactMetadata = stripBundleArtifactMetadata;

package/dist/index.d.cts

@@ -1,3 +1,18 @@
+//#region src/appVersion.d.ts
+/**
+ * The form of an app version that the device and the server compare:
+ * `major.minor.patch` of the first version in `appVersion`, such as `1.4.0`
+ * for `v1.4`, or null when it holds none. Prerelease and build parts are
+ * dropped.
+ */
+declare function canonicalizeAppVersion(appVersion: string): string | null;
+//#endregion
+//#region src/baseURL.d.ts
+/** The server's base URL, or a function that returns it, as the SDK takes it. */
+type HotUpdaterBaseURL = string | (() => string | Promise<string>);
+/** Resolves a functional baseURL and drops trailing slashes. */
+declare const resolveBaseURL: (baseURL: HotUpdaterBaseURL) => Promise<string>;
+//#endregion
 //#region src/types.d.ts
 type Platform = "ios" | "android";
 type BundleMetadata = {
@@ -108,8 +123,7 @@ declare const getPatchStorageUri: (bundle: Pick<Bundle, "patches">) => string;
 /**
  * The client plugin contract. Built-in plugins, such as Insights, and
  * third-party plugins use the same one, as server plugins do. Plugins import
- * it through `@hot-updater/react-native/client-plugin`, and apps through
- * `@hot-updater/react-native`.
+ * it from here, and apps through `@hot-updater/react-native`.
  *
  * Keep this module free of state and of classes that code checks with
  * `instanceof`. A plugin can load it in one module format while the app loads
@@ -295,6 +309,63 @@ interface HotUpdaterClientPlugin {
 /** Declares a client plugin; built-in and third-party plugins use the same contract. */
 declare const defineClientPlugin: <const P extends HotUpdaterClientPlugin>(plugin: P) => P;
 //#endregion
+//#region src/createPluginHost.d.ts
+type PluginHookName = keyof HotUpdaterClientHooks;
+type PluginHookPayload<K extends PluginHookName> = Parameters<NonNullable<HotUpdaterClientHooks[K]>>[0];
+/** The init or wrap settings plugins see through their context. */
+interface PluginHostConfig {
+  readonly baseURL: HotUpdaterBaseURL;
+  readonly requestHeaders?: Record<string, string>;
+  readonly requestTimeout?: number;
+  readonly onError?: (error: unknown) => void;
+}
+/**
+ * What plugins read from the app and the device. A device SDK backs it with
+ * its native module; `@hot-updater/test-utils/react-native` backs it with
+ * fakes.
+ */
+interface PluginHostEnvironment {
+  fetch(url: string, init: RequestInit): Promise<Response>;
+  readonly platform: "ios" | "android";
+  readonly isDebugBuild: boolean;
+  readonly sdkVersion: string;
+  getInstallId(): string;
+  getAppVersion(): string | null;
+  getBundleId(): string;
+  getChannel(): string;
+  getCohort(): string;
+  getFingerprintHash(): string | null;
+  getStorageItem(key: string): string | null;
+  setStorageItem(key: string, value: string | null): void;
+  now(): number;
+}
+interface PluginHost {
+  /**
+   * Sets up the plugins of an init or wrap call. A plugin passed to an
+   * earlier call keeps its hooks, and a plugin left out stops receiving
+   * events.
+   */
+  configurePlugins(plugins: readonly HotUpdaterClientPlugin[] | undefined, config: PluginHostConfig): void;
+  /** Whether any plugin listens to this hook, so callers build events only when one does. */
+  hasPluginHook(name: PluginHookName): boolean;
+  /**
+   * Builds a hook's event when a plugin listens. A failure to build it is
+   * reported, not thrown, since reporting never changes an update.
+   */
+  buildPluginEvent<K extends PluginHookName>(name: K, createPayload: () => PluginHookPayload<K> | null): PluginHookPayload<K> | null;
+  /**
+   * Calls a hook on every plugin that listens, without waiting for any. It
+   * returns when each asynchronous hook settles, for observers such as
+   * `@hot-updater/test-utils`; the SDK ignores it.
+   */
+  dispatchPluginHook<K extends PluginHookName>(name: K, payload: PluginHookPayload<K>): readonly Promise<void>[];
+  /** Builds a hook's event when a plugin listens and calls the hook right away. */
+  emitPluginHook<K extends PluginHookName>(name: K, createPayload: () => PluginHookPayload<K> | null): void;
+}
+/** Where a plugin's key lives in native storage. */
+declare const pluginStorageKey: (pluginId: string, key: string) => string;
+declare const createPluginHost: (environment: PluginHostEnvironment) => PluginHost;
+//#endregion
 //#region src/releaseCatalog.d.ts
 declare const RELEASE_CATALOG_SCHEMA_VERSION: 1;
 declare const RELEASE_CATALOG_FALLBACK_POLICY: "BUILTIN_IF_ACTIVE_INELIGIBLE";
@@ -428,6 +499,32 @@ type ReleaseCatalogScopeKeyInput = {
 declare function createReleaseCatalogScopeKey(input: ReleaseCatalogScopeKeyInput): string;
 declare function parseReleaseCatalogScopeKey(scopeKey: string): ReleaseCatalogScopeKeyInput;
 //#endregion
+//#region src/releaseCatalogWire.d.ts
+/** The largest release catalog response body a client accepts, in UTF-8 bytes. */
+declare const MAX_RELEASE_CATALOG_WIRE_BYTES: number;
+/** The scope a client asked for: the catalog it accepts must be this scope's. */
+type ExpectedReleaseCatalogScope = {
+  readonly channelKey: string;
+  readonly platform: "ios" | "android";
+} & ({
+  readonly strategy: "APP_VERSION";
+  readonly fingerprintHash?: never;
+} | {
+  readonly strategy: "FINGERPRINT";
+  readonly fingerprintHash: string;
+});
+/** The length of `value` in UTF-8 bytes, without an encoder the device may lack. */
+declare const getUtf8ByteLength: (value: string) => number;
+/** Whether the catalog is the expected scope's. */
+declare const hasExpectedReleaseCatalogScope: (catalog: Pick<ReleaseCatalog, "scopeKey">, expected: ExpectedReleaseCatalogScope) => boolean;
+/**
+ * Parses a release catalog response body as a client accepts it: within the
+ * wire limit, in the schema's shape, for the expected scope, and within the
+ * cohort limits. Any other body is null. The device's update client and
+ * doctor's server checks both run this, so they accept the same catalogs.
+ */
+declare const parseReleaseCatalog: (body: string, expectedScope: ExpectedReleaseCatalogScope) => ReleaseCatalog | null;
+//#endregion
 //#region src/rollout.d.ts
 declare const NUMERIC_COHORT_SIZE = 1000;
 declare const DEFAULT_ROLLOUT_COHORT_COUNT = 1000;
@@ -448,4 +545,4 @@ declare function isCohortEligibleForUpdate(bundleId: string, cohort: string | nu
 declare const NIL_UUID = "00000000-0000-0000-0000-000000000000";
 declare const isUUIDv7: (value: unknown) => value is string;
 //#endregion
-export { ARTIFACT_PROTOCOL_VERSION, AppReadyResult, ArtifactAsset, ArtifactAssetFile, ArtifactInfo, Bundle, BundleDownloadedInfo, BundleMetadata, BundlePatchArtifact, CatalogAcceptance, CatalogHighWater, ChangedAssetPatch, DEFAULT_ROLLOUT_COHORT_COUNT, DesiredRelease, HotUpdaterClientContext, HotUpdaterClientHooks, HotUpdaterClientPlugin, HotUpdaterClientStorage, INVALID_COHORT_ERROR_MESSAGE, MAX_COHORT_LENGTH, MAX_COMPILED_CATALOG_BYTES, MAX_CRASHED_BUNDLES, MAX_DISTINCT_TARGET_COHORTS_PER_SCOPE, MAX_TARGET_COHORTS_PER_RELEASE, ManifestArchive, NIL_UUID, NUMERIC_COHORT_SIZE, PersistedSelectionReceipt, Platform, RELEASE_CATALOG_FALLBACK_POLICY, RELEASE_CATALOG_SCHEMA_VERSION, Release, ReleaseCatalog, ReleaseCatalogDescriptor, ReleaseCatalogScopeKeyInput, ReleaseKind, ReleaseOperation, ReleaseSelectionContextInput, ReleaseSelectionInput, ReleaseStrategy, ReleaseTransitionAuthorization, ReleaseTransitionKind, SelectionKind, UpdateCheckResult, UpdateError, UpdateErrorReason, UpdateErrorResource, UpdateErrorStage, UpdateErrorTransport, UpdateStatus, UpdateStrategy, assertCanonicalChannelName, assessCatalogAcceptance, authorizeReleaseTransition, createReleaseCatalogScopeKey, createReleaseSelectionContextHash, decodeChannelKey, defineClientPlugin, encodeChannelKey, getAssetBaseStorageUri, getBundlePatch, getBundlePatches, getDefaultNumericCohort, getManifestFileHash, getManifestStorageUri, getNumericCohortRolloutPosition, getNumericCohortValue, getPatchBaseBundleId, getPatchBaseFileHash, getPatchFileHash, getPatchStorageUri, getRolledOutNumericCohorts, isCohortEligibleForUpdate, isCustomCohort, isNumericCohort, isReleaseEligibleForCohort, isUUIDv7, isValidCohort, normalizeChannelName, normalizeCohortValue, normalizeRolloutCohortCount, parseReleaseCatalogScopeKey, selectDesiredRelease, stripBundleArtifactMetadata };
+export { ARTIFACT_PROTOCOL_VERSION, AppReadyResult, ArtifactAsset, ArtifactAssetFile, ArtifactInfo, Bundle, BundleDownloadedInfo, BundleMetadata, BundlePatchArtifact, CatalogAcceptance, CatalogHighWater, ChangedAssetPatch, DEFAULT_ROLLOUT_COHORT_COUNT, DesiredRelease, ExpectedReleaseCatalogScope, HotUpdaterBaseURL, HotUpdaterClientContext, HotUpdaterClientHooks, HotUpdaterClientPlugin, HotUpdaterClientStorage, INVALID_COHORT_ERROR_MESSAGE, MAX_COHORT_LENGTH, MAX_COMPILED_CATALOG_BYTES, MAX_CRASHED_BUNDLES, MAX_DISTINCT_TARGET_COHORTS_PER_SCOPE, MAX_RELEASE_CATALOG_WIRE_BYTES, MAX_TARGET_COHORTS_PER_RELEASE, ManifestArchive, NIL_UUID, NUMERIC_COHORT_SIZE, PersistedSelectionReceipt, Platform, PluginHookName, PluginHookPayload, PluginHost, PluginHostConfig, PluginHostEnvironment, RELEASE_CATALOG_FALLBACK_POLICY, RELEASE_CATALOG_SCHEMA_VERSION, Release, ReleaseCatalog, ReleaseCatalogDescriptor, ReleaseCatalogScopeKeyInput, ReleaseKind, ReleaseOperation, ReleaseSelectionContextInput, ReleaseSelectionInput, ReleaseStrategy, ReleaseTransitionAuthorization, ReleaseTransitionKind, SelectionKind, UpdateCheckResult, UpdateError, UpdateErrorReason, UpdateErrorResource, UpdateErrorStage, UpdateErrorTransport, UpdateStatus, UpdateStrategy, assertCanonicalChannelName, assessCatalogAcceptance, authorizeReleaseTransition, canonicalizeAppVersion, createPluginHost, createReleaseCatalogScopeKey, createReleaseSelectionContextHash, decodeChannelKey, defineClientPlugin, encodeChannelKey, getAssetBaseStorageUri, getBundlePatch, getBundlePatches, getDefaultNumericCohort, getManifestFileHash, getManifestStorageUri, getNumericCohortRolloutPosition, getNumericCohortValue, getPatchBaseBundleId, getPatchBaseFileHash, getPatchFileHash, getPatchStorageUri, getRolledOutNumericCohorts, getUtf8ByteLength, hasExpectedReleaseCatalogScope, isCohortEligibleForUpdate, isCustomCohort, isNumericCohort, isReleaseEligibleForCohort, isUUIDv7, isValidCohort, normalizeChannelName, normalizeCohortValue, normalizeRolloutCohortCount, parseReleaseCatalog, parseReleaseCatalogScopeKey, pluginStorageKey, resolveBaseURL, selectDesiredRelease, stripBundleArtifactMetadata };

package/dist/index.d.mts

@@ -1,3 +1,18 @@
+//#region src/appVersion.d.ts
+/**
+ * The form of an app version that the device and the server compare:
+ * `major.minor.patch` of the first version in `appVersion`, such as `1.4.0`
+ * for `v1.4`, or null when it holds none. Prerelease and build parts are
+ * dropped.
+ */
+declare function canonicalizeAppVersion(appVersion: string): string | null;
+//#endregion
+//#region src/baseURL.d.ts
+/** The server's base URL, or a function that returns it, as the SDK takes it. */
+type HotUpdaterBaseURL = string | (() => string | Promise<string>);
+/** Resolves a functional baseURL and drops trailing slashes. */
+declare const resolveBaseURL: (baseURL: HotUpdaterBaseURL) => Promise<string>;
+//#endregion
 //#region src/types.d.ts
 type Platform = "ios" | "android";
 type BundleMetadata = {
@@ -108,8 +123,7 @@ declare const getPatchStorageUri: (bundle: Pick<Bundle, "patches">) => string;
 /**
  * The client plugin contract. Built-in plugins, such as Insights, and
  * third-party plugins use the same one, as server plugins do. Plugins import
- * it through `@hot-updater/react-native/client-plugin`, and apps through
- * `@hot-updater/react-native`.
+ * it from here, and apps through `@hot-updater/react-native`.
  *
  * Keep this module free of state and of classes that code checks with
  * `instanceof`. A plugin can load it in one module format while the app loads
@@ -295,6 +309,63 @@ interface HotUpdaterClientPlugin {
 /** Declares a client plugin; built-in and third-party plugins use the same contract. */
 declare const defineClientPlugin: <const P extends HotUpdaterClientPlugin>(plugin: P) => P;
 //#endregion
+//#region src/createPluginHost.d.ts
+type PluginHookName = keyof HotUpdaterClientHooks;
+type PluginHookPayload<K extends PluginHookName> = Parameters<NonNullable<HotUpdaterClientHooks[K]>>[0];
+/** The init or wrap settings plugins see through their context. */
+interface PluginHostConfig {
+  readonly baseURL: HotUpdaterBaseURL;
+  readonly requestHeaders?: Record<string, string>;
+  readonly requestTimeout?: number;
+  readonly onError?: (error: unknown) => void;
+}
+/**
+ * What plugins read from the app and the device. A device SDK backs it with
+ * its native module; `@hot-updater/test-utils/react-native` backs it with
+ * fakes.
+ */
+interface PluginHostEnvironment {
+  fetch(url: string, init: RequestInit): Promise<Response>;
+  readonly platform: "ios" | "android";
+  readonly isDebugBuild: boolean;
+  readonly sdkVersion: string;
+  getInstallId(): string;
+  getAppVersion(): string | null;
+  getBundleId(): string;
+  getChannel(): string;
+  getCohort(): string;
+  getFingerprintHash(): string | null;
+  getStorageItem(key: string): string | null;
+  setStorageItem(key: string, value: string | null): void;
+  now(): number;
+}
+interface PluginHost {
+  /**
+   * Sets up the plugins of an init or wrap call. A plugin passed to an
+   * earlier call keeps its hooks, and a plugin left out stops receiving
+   * events.
+   */
+  configurePlugins(plugins: readonly HotUpdaterClientPlugin[] | undefined, config: PluginHostConfig): void;
+  /** Whether any plugin listens to this hook, so callers build events only when one does. */
+  hasPluginHook(name: PluginHookName): boolean;
+  /**
+   * Builds a hook's event when a plugin listens. A failure to build it is
+   * reported, not thrown, since reporting never changes an update.
+   */
+  buildPluginEvent<K extends PluginHookName>(name: K, createPayload: () => PluginHookPayload<K> | null): PluginHookPayload<K> | null;
+  /**
+   * Calls a hook on every plugin that listens, without waiting for any. It
+   * returns when each asynchronous hook settles, for observers such as
+   * `@hot-updater/test-utils`; the SDK ignores it.
+   */
+  dispatchPluginHook<K extends PluginHookName>(name: K, payload: PluginHookPayload<K>): readonly Promise<void>[];
+  /** Builds a hook's event when a plugin listens and calls the hook right away. */
+  emitPluginHook<K extends PluginHookName>(name: K, createPayload: () => PluginHookPayload<K> | null): void;
+}
+/** Where a plugin's key lives in native storage. */
+declare const pluginStorageKey: (pluginId: string, key: string) => string;
+declare const createPluginHost: (environment: PluginHostEnvironment) => PluginHost;
+//#endregion
 //#region src/releaseCatalog.d.ts
 declare const RELEASE_CATALOG_SCHEMA_VERSION: 1;
 declare const RELEASE_CATALOG_FALLBACK_POLICY: "BUILTIN_IF_ACTIVE_INELIGIBLE";
@@ -428,6 +499,32 @@ type ReleaseCatalogScopeKeyInput = {
 declare function createReleaseCatalogScopeKey(input: ReleaseCatalogScopeKeyInput): string;
 declare function parseReleaseCatalogScopeKey(scopeKey: string): ReleaseCatalogScopeKeyInput;
 //#endregion
+//#region src/releaseCatalogWire.d.ts
+/** The largest release catalog response body a client accepts, in UTF-8 bytes. */
+declare const MAX_RELEASE_CATALOG_WIRE_BYTES: number;
+/** The scope a client asked for: the catalog it accepts must be this scope's. */
+type ExpectedReleaseCatalogScope = {
+  readonly channelKey: string;
+  readonly platform: "ios" | "android";
+} & ({
+  readonly strategy: "APP_VERSION";
+  readonly fingerprintHash?: never;
+} | {
+  readonly strategy: "FINGERPRINT";
+  readonly fingerprintHash: string;
+});
+/** The length of `value` in UTF-8 bytes, without an encoder the device may lack. */
+declare const getUtf8ByteLength: (value: string) => number;
+/** Whether the catalog is the expected scope's. */
+declare const hasExpectedReleaseCatalogScope: (catalog: Pick<ReleaseCatalog, "scopeKey">, expected: ExpectedReleaseCatalogScope) => boolean;
+/**
+ * Parses a release catalog response body as a client accepts it: within the
+ * wire limit, in the schema's shape, for the expected scope, and within the
+ * cohort limits. Any other body is null. The device's update client and
+ * doctor's server checks both run this, so they accept the same catalogs.
+ */
+declare const parseReleaseCatalog: (body: string, expectedScope: ExpectedReleaseCatalogScope) => ReleaseCatalog | null;
+//#endregion
 //#region src/rollout.d.ts
 declare const NUMERIC_COHORT_SIZE = 1000;
 declare const DEFAULT_ROLLOUT_COHORT_COUNT = 1000;
@@ -448,4 +545,4 @@ declare function isCohortEligibleForUpdate(bundleId: string, cohort: string | nu
 declare const NIL_UUID = "00000000-0000-0000-0000-000000000000";
 declare const isUUIDv7: (value: unknown) => value is string;
 //#endregion
-export { ARTIFACT_PROTOCOL_VERSION, AppReadyResult, ArtifactAsset, ArtifactAssetFile, ArtifactInfo, Bundle, BundleDownloadedInfo, BundleMetadata, BundlePatchArtifact, CatalogAcceptance, CatalogHighWater, ChangedAssetPatch, DEFAULT_ROLLOUT_COHORT_COUNT, DesiredRelease, HotUpdaterClientContext, HotUpdaterClientHooks, HotUpdaterClientPlugin, HotUpdaterClientStorage, INVALID_COHORT_ERROR_MESSAGE, MAX_COHORT_LENGTH, MAX_COMPILED_CATALOG_BYTES, MAX_CRASHED_BUNDLES, MAX_DISTINCT_TARGET_COHORTS_PER_SCOPE, MAX_TARGET_COHORTS_PER_RELEASE, ManifestArchive, NIL_UUID, NUMERIC_COHORT_SIZE, PersistedSelectionReceipt, Platform, RELEASE_CATALOG_FALLBACK_POLICY, RELEASE_CATALOG_SCHEMA_VERSION, Release, ReleaseCatalog, ReleaseCatalogDescriptor, ReleaseCatalogScopeKeyInput, ReleaseKind, ReleaseOperation, ReleaseSelectionContextInput, ReleaseSelectionInput, ReleaseStrategy, ReleaseTransitionAuthorization, ReleaseTransitionKind, SelectionKind, UpdateCheckResult, UpdateError, UpdateErrorReason, UpdateErrorResource, UpdateErrorStage, UpdateErrorTransport, UpdateStatus, UpdateStrategy, assertCanonicalChannelName, assessCatalogAcceptance, authorizeReleaseTransition, createReleaseCatalogScopeKey, createReleaseSelectionContextHash, decodeChannelKey, defineClientPlugin, encodeChannelKey, getAssetBaseStorageUri, getBundlePatch, getBundlePatches, getDefaultNumericCohort, getManifestFileHash, getManifestStorageUri, getNumericCohortRolloutPosition, getNumericCohortValue, getPatchBaseBundleId, getPatchBaseFileHash, getPatchFileHash, getPatchStorageUri, getRolledOutNumericCohorts, isCohortEligibleForUpdate, isCustomCohort, isNumericCohort, isReleaseEligibleForCohort, isUUIDv7, isValidCohort, normalizeChannelName, normalizeCohortValue, normalizeRolloutCohortCount, parseReleaseCatalogScopeKey, selectDesiredRelease, stripBundleArtifactMetadata };
+export { ARTIFACT_PROTOCOL_VERSION, AppReadyResult, ArtifactAsset, ArtifactAssetFile, ArtifactInfo, Bundle, BundleDownloadedInfo, BundleMetadata, BundlePatchArtifact, CatalogAcceptance, CatalogHighWater, ChangedAssetPatch, DEFAULT_ROLLOUT_COHORT_COUNT, DesiredRelease, ExpectedReleaseCatalogScope, HotUpdaterBaseURL, HotUpdaterClientContext, HotUpdaterClientHooks, HotUpdaterClientPlugin, HotUpdaterClientStorage, INVALID_COHORT_ERROR_MESSAGE, MAX_COHORT_LENGTH, MAX_COMPILED_CATALOG_BYTES, MAX_CRASHED_BUNDLES, MAX_DISTINCT_TARGET_COHORTS_PER_SCOPE, MAX_RELEASE_CATALOG_WIRE_BYTES, MAX_TARGET_COHORTS_PER_RELEASE, ManifestArchive, NIL_UUID, NUMERIC_COHORT_SIZE, PersistedSelectionReceipt, Platform, PluginHookName, PluginHookPayload, PluginHost, PluginHostConfig, PluginHostEnvironment, RELEASE_CATALOG_FALLBACK_POLICY, RELEASE_CATALOG_SCHEMA_VERSION, Release, ReleaseCatalog, ReleaseCatalogDescriptor, ReleaseCatalogScopeKeyInput, ReleaseKind, ReleaseOperation, ReleaseSelectionContextInput, ReleaseSelectionInput, ReleaseStrategy, ReleaseTransitionAuthorization, ReleaseTransitionKind, SelectionKind, UpdateCheckResult, UpdateError, UpdateErrorReason, UpdateErrorResource, UpdateErrorStage, UpdateErrorTransport, UpdateStatus, UpdateStrategy, assertCanonicalChannelName, assessCatalogAcceptance, authorizeReleaseTransition, canonicalizeAppVersion, createPluginHost, createReleaseCatalogScopeKey, createReleaseSelectionContextHash, decodeChannelKey, defineClientPlugin, encodeChannelKey, getAssetBaseStorageUri, getBundlePatch, getBundlePatches, getDefaultNumericCohort, getManifestFileHash, getManifestStorageUri, getNumericCohortRolloutPosition, getNumericCohortValue, getPatchBaseBundleId, getPatchBaseFileHash, getPatchFileHash, getPatchStorageUri, getRolledOutNumericCohorts, getUtf8ByteLength, hasExpectedReleaseCatalogScope, isCohortEligibleForUpdate, isCustomCohort, isNumericCohort, isReleaseEligibleForCohort, isUUIDv7, isValidCohort, normalizeChannelName, normalizeCohortValue, normalizeRolloutCohortCount, parseReleaseCatalog, parseReleaseCatalogScopeKey, pluginStorageKey, resolveBaseURL, selectDesiredRelease, stripBundleArtifactMetadata };

package/dist/index.mjs

@@ -1,3 +1,129 @@
+//#region ../../node_modules/.pnpm/verkit@0.4.0/node_modules/verkit/dist/comparison-DenM3wCn.js
+const LETTER_DASH_NUMBER = "[a-zA-Z0-9-]";
+const NUMERIC_IDENTIFIER = String.raw`0|[1-9]\d*`;
+const NUMERIC_IDENTIFIER_LOOSE = String.raw`\d+`;
+const NON_NUMERIC_IDENTIFIER = String.raw`\d*[a-zA-Z-]${LETTER_DASH_NUMBER}*`;
+const MAIN_VERSION = String.raw`(${NUMERIC_IDENTIFIER})\.(${NUMERIC_IDENTIFIER})\.(${NUMERIC_IDENTIFIER})`;
+const MAIN_VERSION_LOOSE = String.raw`(${NUMERIC_IDENTIFIER_LOOSE})\.(${NUMERIC_IDENTIFIER_LOOSE})\.(${NUMERIC_IDENTIFIER_LOOSE})`;
+const PRERELEASE_IDENTIFIER = `(?:${NON_NUMERIC_IDENTIFIER}|${NUMERIC_IDENTIFIER})`;
+const PRERELEASE_IDENTIFIER_LOOSE = `(?:${NON_NUMERIC_IDENTIFIER}|${NUMERIC_IDENTIFIER_LOOSE})`;
+const PRERELEASE = String.raw`(?:-(${PRERELEASE_IDENTIFIER}(?:\.${PRERELEASE_IDENTIFIER})*))`;
+const PRERELEASE_LOOSE = String.raw`(?:-?(${PRERELEASE_IDENTIFIER_LOOSE}(?:\.${PRERELEASE_IDENTIFIER_LOOSE})*))`;
+const BUILD_IDENTIFIER = `${LETTER_DASH_NUMBER}+`;
+const BUILD = String.raw`(?:\+(${BUILD_IDENTIFIER}(?:\.${BUILD_IDENTIFIER})*))`;
+const FULL_PLAIN = `v?${MAIN_VERSION}${PRERELEASE}?${BUILD}?`;
+const LOOSE_PLAIN = String.raw`[v=\s]*${MAIN_VERSION_LOOSE}${PRERELEASE_LOOSE}?${BUILD}?`;
+const XRANGE_IDENTIFIER = String.raw`${NUMERIC_IDENTIFIER}|x|X|\*`;
+const XRANGE_IDENTIFIER_LOOSE = String.raw`${NUMERIC_IDENTIFIER_LOOSE}|x|X|\*`;
+String.raw`[v=\s]*(${XRANGE_IDENTIFIER})(?:\.(${XRANGE_IDENTIFIER})(?:\.(${XRANGE_IDENTIFIER})(?:${PRERELEASE})?${BUILD}?)?)?`;
+String.raw`[v=\s]*(${XRANGE_IDENTIFIER_LOOSE})(?:\.(${XRANGE_IDENTIFIER_LOOSE})(?:\.(${XRANGE_IDENTIFIER_LOOSE})(?:${PRERELEASE_LOOSE})?${BUILD}?)?)?`;
+String.raw`(?:\^)`;
+const COERCE_PLAIN = String.raw`(^|[^\d])(\d{1,${16}})(?:\.(\d{1,${16}}))?(?:\.(\d{1,${16}}))?`;
+const COERCE = String.raw`${COERCE_PLAIN}(?:$|[^\d])`;
+const COERCE_FULL = String.raw`${COERCE_PLAIN}(?:${PRERELEASE})?(?:${BUILD})?(?:$|[^\d])`;
+function makeSafeRegexSource(source) {
+	const replacements = [
+		[String.raw`\s`, 1],
+		[String.raw`\d`, 256],
+		[LETTER_DASH_NUMBER, 250]
+	];
+	for (const [token, maximum] of replacements) source = source.split(`${token}*`).join(`${token}{0,${maximum}}`).split(`${token}+`).join(`${token}{1,${maximum}}`);
+	return source;
+}
+function safeRegex(source, flags) {
+	return new RegExp(makeSafeRegexSource(source), flags);
+}
+const FULL = safeRegex(`^${FULL_PLAIN}$`);
+const LOOSE = safeRegex(`^${LOOSE_PLAIN}$`);
+const NUMERIC$1 = /^\d+$/;
+function formatComparableVersion(version) {
+	const base = `${version.major}.${version.minor}.${version.patch}`;
+	return version.prerelease?.length ? `${base}-${version.prerelease.join(".")}` : base;
+}
+function formatFullVersion(version) {
+	const comparable = formatComparableVersion(version);
+	return version.build?.length ? `${comparable}+${version.build.join(".")}` : comparable;
+}
+function parse(version, options = {}) {
+	if (typeof version !== "string") return version;
+	if (version.length > 256) throw new TypeError(`Version exceeds the maximum length of 256 characters`);
+	const match = version.trim().match(options.loose ? LOOSE : FULL);
+	if (!match) throw new TypeError(`Invalid version syntax: ${version}`);
+	const major = Number(match[1]);
+	const minor = Number(match[2]);
+	const patch = Number(match[3]);
+	if (major > Number.MAX_SAFE_INTEGER || major < 0) throw new TypeError(`Invalid major version: ${match[1]}`);
+	if (minor > Number.MAX_SAFE_INTEGER || minor < 0) throw new TypeError(`Invalid minor version: ${match[2]}`);
+	if (patch > Number.MAX_SAFE_INTEGER || patch < 0) throw new TypeError(`Invalid patch version: ${match[3]}`);
+	const prerelease = match[4] ? match[4].split(".").map((identifier) => {
+		if (NUMERIC$1.test(identifier)) {
+			const numeric = Number(identifier);
+			if (numeric >= 0 && numeric < Number.MAX_SAFE_INTEGER) return numeric;
+		}
+		return identifier;
+	}) : void 0;
+	return {
+		build: match[5]?.split("."),
+		major,
+		minor,
+		patch,
+		prerelease
+	};
+}
+function tryParse(version, options = {}) {
+	try {
+		return parse(version, options);
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region ../../node_modules/.pnpm/verkit@0.4.0/node_modules/verkit/dist/version-CQ98ZBpL.js
+const COERCE_EXACT = safeRegex(COERCE);
+const COERCE_FULL_EXACT = safeRegex(COERCE_FULL);
+safeRegex(`^${PRERELEASE}$`);
+safeRegex(`^${PRERELEASE_LOOSE}$`);
+function normalizeFull(version, options = {}) {
+	const parsed = tryParse(version, options);
+	return parsed ? formatFullVersion(parsed) : null;
+}
+function coerce(value, options = {}) {
+	if (typeof value === "object") return value;
+	const input = typeof value === "number" ? String(value) : value;
+	let match = null;
+	if (options.rtl) {
+		const expression = safeRegex(options.includePrerelease ? COERCE_FULL : COERCE, "g");
+		let next;
+		while ((next = expression.exec(input)) && (!match || match.index + match[0].length !== input.length)) {
+			if (!match || next.index + next[0].length !== match.index + match[0].length) match = next;
+			expression.lastIndex = next.index + next[1].length + next[2].length;
+		}
+	} else match = (options.includePrerelease ? COERCE_FULL_EXACT : COERCE_EXACT).exec(input);
+	if (!match) return null;
+	const major = match[2];
+	return tryParse(`${major}.${match[3] || "0"}.${match[4] || "0"}${options.includePrerelease && match[5] ? `-${match[5]}` : ""}${options.includePrerelease && match[6] ? `+${match[6]}` : ""}`, options);
+}
+//#endregion
+//#region src/appVersion.ts
+/**
+* The form of an app version that the device and the server compare:
+* `major.minor.patch` of the first version in `appVersion`, such as `1.4.0`
+* for `v1.4`, or null when it holds none. Prerelease and build parts are
+* dropped.
+*/
+function canonicalizeAppVersion(appVersion) {
+	const version = coerce(appVersion);
+	return version ? normalizeFull(version) : null;
+}
+//#endregion
+//#region src/baseURL.ts
+/** Resolves a functional baseURL and drops trailing slashes. */
+const resolveBaseURL = async (baseURL) => {
+	const resolvedBaseURL = typeof baseURL === "function" ? await baseURL() : baseURL;
+	if (!resolvedBaseURL) throw new Error("baseURL function must return a non-empty string");
+	return resolvedBaseURL.replace(/\/+$/, "");
+};
+//#endregion
 //#region src/bundleArtifacts.ts
 const stripBundleArtifactMetadata = (metadata) => metadata;
 const getManifestStorageUri = (bundle) => bundle.manifestStorageUri;
@@ -36,6 +162,164 @@ const getPatchStorageUri = (bundle) => getPrimaryPatch(bundle)?.patchStorageUri
 /** Declares a client plugin; built-in and third-party plugins use the same contract. */
 const defineClientPlugin = (plugin) => plugin;
 //#endregion
+//#region src/createPluginHost.ts
+/** Storage values stay small, since native reads them on the JS thread. */
+const MAX_STORAGE_VALUE_LENGTH = 65536;
+/** Where a plugin's key lives in native storage. */
+const pluginStorageKey = (pluginId, key) => `plugins/${encodeURIComponent(pluginId)}/${key}`;
+const createPluginHost = (environment) => {
+	let config = null;
+	/** Hooks by plugin, so a plugin configured again is not set up twice. */
+	const setUpPlugins = /* @__PURE__ */ new WeakMap();
+	let activePlugins = [];
+	/** What plugins read and wrote, so a read follows a write before native does. */
+	const storageValues = /* @__PURE__ */ new Map();
+	const reportHookError = (message, error) => {
+		const report = new Error(`[HotUpdater] ${message}`, { cause: error });
+		try {
+			if (config?.onError) {
+				config.onError(report);
+				return;
+			}
+		} catch {}
+		console.warn(report.message, error);
+	};
+	const fetchFromServer = async (path, init = {}) => {
+		if (config === null) throw new Error("[HotUpdater] Plugins can fetch only after init or wrap.");
+		if (/^[a-z][a-z\d+.-]*:/i.test(path) || path.startsWith("//")) throw new TypeError("[HotUpdater] Plugin fetch takes a path relative to baseURL.");
+		const { requestHeaders, requestTimeout } = config;
+		const url = `${await resolveBaseURL(config.baseURL)}/${path.replace(/^\/+/, "")}`;
+		const headers = new Headers(requestHeaders);
+		new Headers(init.headers).forEach((value, name) => {
+			headers.set(name, value);
+		});
+		const controller = new AbortController();
+		const callerSignal = init.signal;
+		const abortFromCaller = () => controller.abort();
+		if (callerSignal?.aborted) controller.abort();
+		callerSignal?.addEventListener("abort", abortFromCaller);
+		const timeoutId = setTimeout(() => controller.abort(), requestTimeout ?? 5e3);
+		try {
+			return await environment.fetch(url, {
+				...init,
+				headers,
+				signal: controller.signal
+			});
+		} catch (error) {
+			if (error instanceof Error && error.name === "AbortError" && !callerSignal?.aborted) throw new Error("Request timed out");
+			throw error;
+		} finally {
+			clearTimeout(timeoutId);
+			callerSignal?.removeEventListener("abort", abortFromCaller);
+		}
+	};
+	const createStorage = (pluginId) => {
+		const scopedKey = (key) => {
+			if (typeof key !== "string" || key.length === 0) throw new TypeError("[HotUpdater] Plugin storage keys are non-empty strings.");
+			return pluginStorageKey(pluginId, key);
+		};
+		return {
+			get: (key) => {
+				const storageKey = scopedKey(key);
+				const cached = storageValues.get(storageKey);
+				if (cached !== void 0) return cached;
+				const value = environment.getStorageItem(storageKey);
+				storageValues.set(storageKey, value);
+				return value;
+			},
+			set: (key, value) => {
+				const storageKey = scopedKey(key);
+				if (value !== null && typeof value !== "string") throw new TypeError("[HotUpdater] Plugin storage values are strings or null.");
+				if (value !== null && value.length > MAX_STORAGE_VALUE_LENGTH) throw new RangeError("[HotUpdater] Plugin storage values are at most 64 KB.");
+				environment.setStorageItem(storageKey, value);
+				storageValues.set(storageKey, value);
+			}
+		};
+	};
+	const createContext = (pluginId) => ({
+		fetch: fetchFromServer,
+		get installId() {
+			return environment.getInstallId();
+		},
+		platform: environment.platform,
+		get appVersion() {
+			return environment.getAppVersion();
+		},
+		get sdkVersion() {
+			return environment.sdkVersion;
+		},
+		isDebugBuild: environment.isDebugBuild,
+		getBundleId: () => environment.getBundleId(),
+		getChannel: () => environment.getChannel(),
+		getCohort: () => environment.getCohort(),
+		getFingerprintHash: () => environment.getFingerprintHash(),
+		storage: createStorage(pluginId),
+		now: () => environment.now()
+	});
+	const configurePlugins = (plugins, nextConfig) => {
+		const ids = /* @__PURE__ */ new Set();
+		for (const plugin of plugins ?? []) {
+			if (typeof plugin.id !== "string" || plugin.id.length === 0) throw new Error("[HotUpdater] A plugin id must be a non-empty string.");
+			if (ids.has(plugin.id)) throw new Error(`[HotUpdater] Two plugins use the id "${plugin.id}". Plugin ids must be unique.`);
+			ids.add(plugin.id);
+		}
+		config = nextConfig;
+		activePlugins = (plugins ?? []).map((plugin) => {
+			let hooks = setUpPlugins.get(plugin);
+			if (hooks === void 0) {
+				try {
+					hooks = plugin.setup(createContext(plugin.id)) ?? {};
+				} catch (error) {
+					reportHookError(`Plugin "${plugin.id}" failed in setup`, error);
+					hooks = {};
+				}
+				setUpPlugins.set(plugin, hooks);
+			}
+			return {
+				plugin,
+				hooks
+			};
+		});
+	};
+	const hasPluginHook = (name) => activePlugins.some(({ hooks }) => typeof hooks[name] === "function");
+	const buildPluginEvent = (name, createPayload) => {
+		if (!hasPluginHook(name)) return null;
+		try {
+			return createPayload();
+		} catch (error) {
+			reportHookError(`Failed to build the ${name} event for plugins`, error);
+			return null;
+		}
+	};
+	const dispatchPluginHook = (name, payload) => {
+		const settlements = [];
+		for (const { plugin, hooks } of activePlugins) {
+			const hook = hooks[name];
+			if (typeof hook !== "function") continue;
+			try {
+				const result = hook.call(hooks, payload);
+				if (result !== null && typeof result === "object" && typeof result.then === "function") settlements.push(Promise.resolve(result).then(() => void 0, (error) => {
+					reportHookError(`Plugin "${plugin.id}" failed in ${name}`, error);
+				}));
+			} catch (error) {
+				reportHookError(`Plugin "${plugin.id}" failed in ${name}`, error);
+			}
+		}
+		return settlements;
+	};
+	const emitPluginHook = (name, createPayload) => {
+		const payload = buildPluginEvent(name, createPayload);
+		if (payload !== null) dispatchPluginHook(name, payload);
+	};
+	return {
+		configurePlugins,
+		hasPluginHook,
+		buildPluginEvent,
+		dispatchPluginHook,
+		emitPluginHook
+	};
+};
+//#endregion
 //#region src/rollout.ts
 const NUMERIC_COHORT_SIZE = 1e3;
 const DEFAULT_ROLLOUT_COHORT_COUNT = NUMERIC_COHORT_SIZE;
@@ -407,12 +691,63 @@ function parseReleaseCatalogScopeKey(scopeKey) {
 	return input;
 }
 //#endregion
-//#region src/types.ts
-const ARTIFACT_PROTOCOL_VERSION = 1;
-//#endregion
 //#region src/uuid.ts
 const NIL_UUID = "00000000-0000-0000-0000-000000000000";
 const UUID_V7_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
 const isUUIDv7 = (value) => typeof value === "string" && UUID_V7_PATTERN.test(value);
 //#endregion
-export { ARTIFACT_PROTOCOL_VERSION, DEFAULT_ROLLOUT_COHORT_COUNT, INVALID_COHORT_ERROR_MESSAGE, MAX_COHORT_LENGTH, MAX_COMPILED_CATALOG_BYTES, MAX_CRASHED_BUNDLES, MAX_DISTINCT_TARGET_COHORTS_PER_SCOPE, MAX_TARGET_COHORTS_PER_RELEASE, NIL_UUID, NUMERIC_COHORT_SIZE, RELEASE_CATALOG_FALLBACK_POLICY, RELEASE_CATALOG_SCHEMA_VERSION, assertCanonicalChannelName, assessCatalogAcceptance, authorizeReleaseTransition, createReleaseCatalogScopeKey, createReleaseSelectionContextHash, decodeChannelKey, defineClientPlugin, encodeChannelKey, getAssetBaseStorageUri, getBundlePatch, getBundlePatches, getDefaultNumericCohort, getManifestFileHash, getManifestStorageUri, getNumericCohortRolloutPosition, getNumericCohortValue, getPatchBaseBundleId, getPatchBaseFileHash, getPatchFileHash, getPatchStorageUri, getRolledOutNumericCohorts, isCohortEligibleForUpdate, isCustomCohort, isNumericCohort, isReleaseEligibleForCohort, isUUIDv7, isValidCohort, normalizeChannelName, normalizeCohortValue, normalizeRolloutCohortCount, parseReleaseCatalogScopeKey, selectDesiredRelease, stripBundleArtifactMetadata };
+//#region src/releaseCatalogWire.ts
+/** The largest release catalog response body a client accepts, in UTF-8 bytes. */
+const MAX_RELEASE_CATALOG_WIRE_BYTES = 528384;
+/** The length of `value` in UTF-8 bytes, without an encoder the device may lack. */
+const getUtf8ByteLength = (value) => {
+	let bytes = 0;
+	for (let index = 0; index < value.length; index += 1) {
+		const code = value.charCodeAt(index);
+		if (code <= 127) bytes += 1;
+		else if (code <= 2047) bytes += 2;
+		else if (code >= 55296 && code <= 56319 && index + 1 < value.length && value.charCodeAt(index + 1) >= 56320 && value.charCodeAt(index + 1) <= 57343) {
+			bytes += 4;
+			index += 1;
+		} else bytes += 3;
+	}
+	return bytes;
+};
+const isStringArray = (value) => Array.isArray(value) && value.every((entry) => typeof entry === "string");
+const isValidReleaseDescriptor = (value) => {
+	if (value === null || typeof value !== "object") return false;
+	const descriptor = value;
+	return isUUIDv7(descriptor.releaseId) && (descriptor.kind === "BUNDLE" || descriptor.kind === "EMBEDDED") && (descriptor.kind === "BUNDLE" && typeof descriptor.bundleId === "string" || descriptor.kind === "EMBEDDED" && descriptor.bundleId === null) && Number.isSafeInteger(descriptor.rolloutCohortCount) && descriptor.rolloutCohortCount >= 0 && descriptor.rolloutCohortCount <= 1e3 && isStringArray(descriptor.targetCohorts) && descriptor.targetCohorts.length <= 100 && typeof descriptor.shouldForceUpdate === "boolean" && (descriptor.message === null || typeof descriptor.message === "string");
+};
+/** Whether the catalog is the expected scope's. */
+const hasExpectedReleaseCatalogScope = (catalog, expected) => {
+	try {
+		const parsed = parseReleaseCatalogScopeKey(catalog.scopeKey);
+		return parsed.channelKey === expected.channelKey && parsed.platform === expected.platform && parsed.strategy === expected.strategy && (parsed.strategy === "APP_VERSION" || expected.strategy === "FINGERPRINT" && parsed.fingerprintHash === expected.fingerprintHash);
+	} catch {
+		return false;
+	}
+};
+/**
+* Parses a release catalog response body as a client accepts it: within the
+* wire limit, in the schema's shape, for the expected scope, and within the
+* cohort limits. Any other body is null. The device's update client and
+* doctor's server checks both run this, so they accept the same catalogs.
+*/
+const parseReleaseCatalog = (body, expectedScope) => {
+	if (getUtf8ByteLength(body) > MAX_RELEASE_CATALOG_WIRE_BYTES) return null;
+	try {
+		const catalog = JSON.parse(body);
+		if (catalog.schemaVersion !== 1 || typeof catalog.catalogId !== "string" || catalog.catalogId.length === 0 || typeof catalog.scopeKey !== "string" || !Number.isSafeInteger(catalog.generation) || (catalog.generation ?? 0) < 1 || typeof catalog.catalogHash !== "string" || !/^sha256:[0-9a-f]{64}$/.test(catalog.catalogHash) || catalog.fallbackPolicy !== "BUILTIN_IF_ACTIVE_INELIGIBLE" || !Array.isArray(catalog.releases) || !catalog.releases.every(isValidReleaseDescriptor) || catalog.rollbackReleases !== void 0 && (!Array.isArray(catalog.rollbackReleases) || !catalog.rollbackReleases.every(isValidReleaseDescriptor))) return null;
+		if (!hasExpectedReleaseCatalogScope(catalog, expectedScope)) return null;
+		if (new Set([...catalog.releases, ...catalog.rollbackReleases ?? []].flatMap((release) => release.targetCohorts)).size > 512) return null;
+		return catalog;
+	} catch {
+		return null;
+	}
+};
+//#endregion
+//#region src/types.ts
+const ARTIFACT_PROTOCOL_VERSION = 1;
+//#endregion
+export { ARTIFACT_PROTOCOL_VERSION, DEFAULT_ROLLOUT_COHORT_COUNT, INVALID_COHORT_ERROR_MESSAGE, MAX_COHORT_LENGTH, MAX_COMPILED_CATALOG_BYTES, MAX_CRASHED_BUNDLES, MAX_DISTINCT_TARGET_COHORTS_PER_SCOPE, MAX_RELEASE_CATALOG_WIRE_BYTES, MAX_TARGET_COHORTS_PER_RELEASE, NIL_UUID, NUMERIC_COHORT_SIZE, RELEASE_CATALOG_FALLBACK_POLICY, RELEASE_CATALOG_SCHEMA_VERSION, assertCanonicalChannelName, assessCatalogAcceptance, authorizeReleaseTransition, canonicalizeAppVersion, createPluginHost, createReleaseCatalogScopeKey, createReleaseSelectionContextHash, decodeChannelKey, defineClientPlugin, encodeChannelKey, getAssetBaseStorageUri, getBundlePatch, getBundlePatches, getDefaultNumericCohort, getManifestFileHash, getManifestStorageUri, getNumericCohortRolloutPosition, getNumericCohortValue, getPatchBaseBundleId, getPatchBaseFileHash, getPatchFileHash, getPatchStorageUri, getRolledOutNumericCohorts, getUtf8ByteLength, hasExpectedReleaseCatalogScope, isCohortEligibleForUpdate, isCustomCohort, isNumericCohort, isReleaseEligibleForCohort, isUUIDv7, isValidCohort, normalizeChannelName, normalizeCohortValue, normalizeRolloutCohortCount, parseReleaseCatalog, parseReleaseCatalogScopeKey, pluginStorageKey, resolveBaseURL, selectDesiredRelease, stripBundleArtifactMetadata };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@hot-updater/protocol",
-  "version": "1.0.0-rc.20",
+  "version": "1.0.0-rc.21",
   "type": "module",
-  "description": "Data formats and pure computations shared by the Hot Updater app and server.",
+  "description": "The data formats and pure computations that Hot Updater's app and server share",
   "sideEffects": false,
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -42,7 +42,11 @@
     "access": "public"
   },
   "devDependencies": {
-    "@types/node": "^20"
+    "@types/node": "^20",
+    "verkit": "0.4.0"
+  },
+  "inlinedDependencies": {
+    "verkit": "0.4.0"
   },
   "scripts": {
     "build": "tsdown",