@hot-updater/protocol 1.1.4 → 1.2.0-rc.0

package/dist/native-artifact.d.cts

@@ -0,0 +1,179 @@
+//#region src/nativeArtifact/byteSource.d.ts
+/**
+ * Random access to an artifact's bytes, so a reader takes only the parts it
+ * needs of a file of hundreds of megabytes: a file on disk (Node's
+ * `fs.openAsBlob`), or bytes in memory.
+ */
+interface ByteSource {
+  /** The artifact's length in bytes. */
+  readonly size: number;
+  /** The bytes in `[offset, offset + length)`, fewer only at the end. */
+  read(offset: number, length: number): Promise<Uint8Array>;
+}
+/** A `Blob`, such as Node's `fs.openAsBlob`, read by slices. */
+declare const blobSource: (blob: Blob) => ByteSource;
+/** Why an artifact can't be read, or can't serve as a native build. */
+declare class NativeArtifactError extends Error {
+  readonly code: NativeArtifactProblemCode;
+  readonly name = "NativeArtifactError";
+  constructor(code: NativeArtifactProblemCode, message: string);
+}
+/**
+ * What can keep an artifact from being imported as a native build: the
+ * codes `native-build import --json` reports.
+ */
+type NativeArtifactProblemCode = "UNSUPPORTED_FILE" | "UNREADABLE" | "NO_BUILT_IN_BUNDLE" | "NO_MIN_BUNDLE_ID" | "AMBIGUOUS_MIN_BUNDLE_ID" | "NO_FINGERPRINT" | "AMBIGUOUS_FINGERPRINT" | "NO_APP_VERSION" | "INVALID_SCOPE" | "APP_ID_MISMATCH" | "ALREADY_IMPORTED";
+//#endregion
+//#region src/nativeArtifact/readNativeArtifact.d.ts
+/**
+ * The kinds of artifact a build made elsewhere can be imported from: the
+ * store artifacts, and a simulator `.app` as one zip archive (`.app.zip`,
+ * the `.app` directory at its root, as Finder and `ditto` archive it).
+ */
+type NativeArtifactKind = "ipa" | "aab" | "apk" | "app";
+/** A value the artifact holds as something import can't read exactly. */
+interface UnreadableValue {
+  readonly unreadable: string;
+}
+/**
+ * What a store artifact compiled in, read from the artifact alone: what its
+ * app reports at runtime, and the built-in bundle it ships.
+ */
+interface NativeArtifactInfo {
+  readonly platform: "ios" | "android";
+  readonly kind: NativeArtifactKind;
+  /** The bundle identifier or application ID. */
+  readonly appId: string | null;
+  /** `CFBundleShortVersionString` or `versionName`. */
+  readonly appVersion: string | UnreadableValue | null;
+  /** `CFBundleVersion` or `versionCode`. */
+  readonly buildNumber: string | null;
+  /**
+   * `HOT_UPDATER_CHANNEL` or the `com.hotupdater.CHANNEL` meta-data: null
+   * without one, which the native SDK reports as `production`.
+   */
+  readonly channel: string | UnreadableValue | null;
+  /**
+   * The UUIDv7 string literals in the app's code. MIN_BUNDLE_ID is one: the
+   * native SDK's build step compiles it in.
+   */
+  readonly minBundleIdCandidates: readonly string[];
+  /**
+   * The SHA-256 hex string literals in the app's code. A build of an app
+   * with fingerprint.json compiles its fingerprint in as one.
+   */
+  readonly fingerprintCandidates: readonly string[];
+  /** The JavaScript bundle the build packed, the built-in bundle. */
+  readonly builtInBundle: {
+    readonly path: string;
+    readonly byteSize: number;
+  } | null;
+}
+/**
+ * Reads a store artifact (`.ipa`, `.aab` or `.apk`) by its file name's
+ * extension: what its app reports at runtime, and its built-in bundle. It
+ * reads the archive's directory, the manifest or Info.plist, and the app's
+ * code, but not the built-in bundle, so a large artifact is never held
+ * whole. Whether the result can be imported is `checkNativeArtifact`'s.
+ */
+declare const readNativeArtifact: (source: ByteSource, fileName: string, { timeoutMs }?: {
+  readonly timeoutMs?: number;
+}) => Promise<NativeArtifactInfo>;
+//#endregion
+//#region src/nativeArtifact/checkNativeArtifact.d.ts
+/** Why an artifact can't be imported, as `native-build import` says it. */
+interface NativeArtifactProblem {
+  readonly code: NativeArtifactProblemCode;
+  readonly message: string;
+  /** With `ALREADY_IMPORTED`, the native build already registered. */
+  readonly nativeBuildId?: string;
+}
+/** What an importable artifact registers as: a native build and its scope. */
+interface ImportableNativeBuild {
+  readonly platform: "ios" | "android";
+  readonly kind: NativeArtifactKind;
+  readonly appId: string | null;
+  readonly buildNumber: string | null;
+  /** The MIN_BUNDLE_ID compiled in, the built-in bundle's ID. */
+  readonly minBundleId: string;
+  /** The channel the app reports: its own, or `production` without one. */
+  readonly channel: string;
+  readonly fingerprintHash: string | null;
+  readonly appVersion: string | null;
+  /** The built-in bundle's entry in the archive. */
+  readonly builtInBundlePath: string;
+}
+type NativeArtifactCheck = ({
+  readonly ok: true;
+  readonly build: ImportableNativeBuild;
+} | {
+  readonly ok: false;
+  readonly problems: readonly NativeArtifactProblem[];
+}) & {
+  /**
+   * What may be wrong, but doesn't stop the import: an app ID that no
+   * `nativeBuild` scheme declares, which a scheme names only as a hint.
+   */
+  readonly warnings: readonly NativeArtifactProblem[];
+};
+/**
+ * Whether a read artifact can be imported as a native build, whose built-in
+ * bundle OTAs patch from, and what it registers as. It refuses an artifact
+ * that ships no built-in bundle, such as a debug build, which loads its
+ * JavaScript from Metro, one built without the native SDK's build step (no MIN_BUNDLE_ID), and
+ * one the project's update strategy can't place: no fingerprint under the
+ * fingerprint strategy, or no app version a device compares under the
+ * appVersion strategy. With `appIds`, the identifiers the project's
+ * `nativeBuild` schemes name, it warns about an artifact of another app.
+ */
+declare const checkNativeArtifact: (info: NativeArtifactInfo, { updateStrategy, appIds, channel: channelOverride }: {
+  readonly updateStrategy: "fingerprint" | "appVersion";
+  readonly appIds?: readonly string[];
+  /**
+   * The channel the app reports, when it isn't the one the artifact
+   * compiled in: one its code sets, such as `HotUpdaterOptions(channel)`,
+   * or one it switches to at runtime.
+   */
+  readonly channel?: string;
+}) => NativeArtifactCheck;
+/**
+ * The refusal of an artifact whose built-in bundle is already registered:
+ * the registry takes a MIN_BUNDLE_ID once.
+ */
+declare const alreadyImportedProblem: (minBundleId: string, nativeBuildId: string | null) => NativeArtifactProblem;
+//#endregion
+//#region src/nativeArtifact/zip.d.ts
+/** One file of a zip archive, from its central directory. */
+interface ZipEntry {
+  readonly name: string;
+  /**
+   * A name no artifact holds: absolute, with a `..` segment, a backslash or
+   * a NUL. No lookup matches it.
+   */
+  readonly unsafe: boolean;
+  /** A symbolic link, whose data is a path, not a file's bytes. */
+  readonly symlink: boolean;
+  /** 0 stored, 8 deflated. */
+  readonly method: number;
+  readonly compressedSize: number;
+  readonly uncompressedSize: number;
+  readonly localHeaderOffset: number;
+}
+/** Every entry of a zip archive, reading only its central directory. */
+declare const readZipDirectory: (source: ByteSource) => Promise<ZipEntry[]>;
+/**
+ * The one entry an artifact's reader takes by `name`: a symbolic link, or a
+ * name the archive holds twice, which could hand the reader other bytes
+ * than an installer reads, is refused. Unsafe names match nothing.
+ */
+declare const findZipEntry: (entries: readonly ZipEntry[], match: string | ((name: string) => boolean)) => ZipEntry | undefined;
+/**
+ * An entry's uncompressed bytes as a stream, read from the source a chunk at
+ * a time, so a large entry is never held whole.
+ */
+declare const openZipEntry: (source: ByteSource, entry: ZipEntry, { maxBytes }?: {
+  /** The most the entry may inflate to, whatever its header says. */
+  readonly maxBytes?: number;
+}) => Promise<ReadableStream<Uint8Array>>;
+//#endregion
+export { type ByteSource, type ImportableNativeBuild, type NativeArtifactCheck, NativeArtifactError, type NativeArtifactInfo, type NativeArtifactKind, type NativeArtifactProblem, type NativeArtifactProblemCode, type UnreadableValue, type ZipEntry, alreadyImportedProblem, blobSource, checkNativeArtifact, findZipEntry, openZipEntry, readNativeArtifact, readZipDirectory };

package/dist/native-artifact.d.mts

@@ -0,0 +1,179 @@
+//#region src/nativeArtifact/byteSource.d.ts
+/**
+ * Random access to an artifact's bytes, so a reader takes only the parts it
+ * needs of a file of hundreds of megabytes: a file on disk (Node's
+ * `fs.openAsBlob`), or bytes in memory.
+ */
+interface ByteSource {
+  /** The artifact's length in bytes. */
+  readonly size: number;
+  /** The bytes in `[offset, offset + length)`, fewer only at the end. */
+  read(offset: number, length: number): Promise<Uint8Array>;
+}
+/** A `Blob`, such as Node's `fs.openAsBlob`, read by slices. */
+declare const blobSource: (blob: Blob) => ByteSource;
+/** Why an artifact can't be read, or can't serve as a native build. */
+declare class NativeArtifactError extends Error {
+  readonly code: NativeArtifactProblemCode;
+  readonly name = "NativeArtifactError";
+  constructor(code: NativeArtifactProblemCode, message: string);
+}
+/**
+ * What can keep an artifact from being imported as a native build: the
+ * codes `native-build import --json` reports.
+ */
+type NativeArtifactProblemCode = "UNSUPPORTED_FILE" | "UNREADABLE" | "NO_BUILT_IN_BUNDLE" | "NO_MIN_BUNDLE_ID" | "AMBIGUOUS_MIN_BUNDLE_ID" | "NO_FINGERPRINT" | "AMBIGUOUS_FINGERPRINT" | "NO_APP_VERSION" | "INVALID_SCOPE" | "APP_ID_MISMATCH" | "ALREADY_IMPORTED";
+//#endregion
+//#region src/nativeArtifact/readNativeArtifact.d.ts
+/**
+ * The kinds of artifact a build made elsewhere can be imported from: the
+ * store artifacts, and a simulator `.app` as one zip archive (`.app.zip`,
+ * the `.app` directory at its root, as Finder and `ditto` archive it).
+ */
+type NativeArtifactKind = "ipa" | "aab" | "apk" | "app";
+/** A value the artifact holds as something import can't read exactly. */
+interface UnreadableValue {
+  readonly unreadable: string;
+}
+/**
+ * What a store artifact compiled in, read from the artifact alone: what its
+ * app reports at runtime, and the built-in bundle it ships.
+ */
+interface NativeArtifactInfo {
+  readonly platform: "ios" | "android";
+  readonly kind: NativeArtifactKind;
+  /** The bundle identifier or application ID. */
+  readonly appId: string | null;
+  /** `CFBundleShortVersionString` or `versionName`. */
+  readonly appVersion: string | UnreadableValue | null;
+  /** `CFBundleVersion` or `versionCode`. */
+  readonly buildNumber: string | null;
+  /**
+   * `HOT_UPDATER_CHANNEL` or the `com.hotupdater.CHANNEL` meta-data: null
+   * without one, which the native SDK reports as `production`.
+   */
+  readonly channel: string | UnreadableValue | null;
+  /**
+   * The UUIDv7 string literals in the app's code. MIN_BUNDLE_ID is one: the
+   * native SDK's build step compiles it in.
+   */
+  readonly minBundleIdCandidates: readonly string[];
+  /**
+   * The SHA-256 hex string literals in the app's code. A build of an app
+   * with fingerprint.json compiles its fingerprint in as one.
+   */
+  readonly fingerprintCandidates: readonly string[];
+  /** The JavaScript bundle the build packed, the built-in bundle. */
+  readonly builtInBundle: {
+    readonly path: string;
+    readonly byteSize: number;
+  } | null;
+}
+/**
+ * Reads a store artifact (`.ipa`, `.aab` or `.apk`) by its file name's
+ * extension: what its app reports at runtime, and its built-in bundle. It
+ * reads the archive's directory, the manifest or Info.plist, and the app's
+ * code, but not the built-in bundle, so a large artifact is never held
+ * whole. Whether the result can be imported is `checkNativeArtifact`'s.
+ */
+declare const readNativeArtifact: (source: ByteSource, fileName: string, { timeoutMs }?: {
+  readonly timeoutMs?: number;
+}) => Promise<NativeArtifactInfo>;
+//#endregion
+//#region src/nativeArtifact/checkNativeArtifact.d.ts
+/** Why an artifact can't be imported, as `native-build import` says it. */
+interface NativeArtifactProblem {
+  readonly code: NativeArtifactProblemCode;
+  readonly message: string;
+  /** With `ALREADY_IMPORTED`, the native build already registered. */
+  readonly nativeBuildId?: string;
+}
+/** What an importable artifact registers as: a native build and its scope. */
+interface ImportableNativeBuild {
+  readonly platform: "ios" | "android";
+  readonly kind: NativeArtifactKind;
+  readonly appId: string | null;
+  readonly buildNumber: string | null;
+  /** The MIN_BUNDLE_ID compiled in, the built-in bundle's ID. */
+  readonly minBundleId: string;
+  /** The channel the app reports: its own, or `production` without one. */
+  readonly channel: string;
+  readonly fingerprintHash: string | null;
+  readonly appVersion: string | null;
+  /** The built-in bundle's entry in the archive. */
+  readonly builtInBundlePath: string;
+}
+type NativeArtifactCheck = ({
+  readonly ok: true;
+  readonly build: ImportableNativeBuild;
+} | {
+  readonly ok: false;
+  readonly problems: readonly NativeArtifactProblem[];
+}) & {
+  /**
+   * What may be wrong, but doesn't stop the import: an app ID that no
+   * `nativeBuild` scheme declares, which a scheme names only as a hint.
+   */
+  readonly warnings: readonly NativeArtifactProblem[];
+};
+/**
+ * Whether a read artifact can be imported as a native build, whose built-in
+ * bundle OTAs patch from, and what it registers as. It refuses an artifact
+ * that ships no built-in bundle, such as a debug build, which loads its
+ * JavaScript from Metro, one built without the native SDK's build step (no MIN_BUNDLE_ID), and
+ * one the project's update strategy can't place: no fingerprint under the
+ * fingerprint strategy, or no app version a device compares under the
+ * appVersion strategy. With `appIds`, the identifiers the project's
+ * `nativeBuild` schemes name, it warns about an artifact of another app.
+ */
+declare const checkNativeArtifact: (info: NativeArtifactInfo, { updateStrategy, appIds, channel: channelOverride }: {
+  readonly updateStrategy: "fingerprint" | "appVersion";
+  readonly appIds?: readonly string[];
+  /**
+   * The channel the app reports, when it isn't the one the artifact
+   * compiled in: one its code sets, such as `HotUpdaterOptions(channel)`,
+   * or one it switches to at runtime.
+   */
+  readonly channel?: string;
+}) => NativeArtifactCheck;
+/**
+ * The refusal of an artifact whose built-in bundle is already registered:
+ * the registry takes a MIN_BUNDLE_ID once.
+ */
+declare const alreadyImportedProblem: (minBundleId: string, nativeBuildId: string | null) => NativeArtifactProblem;
+//#endregion
+//#region src/nativeArtifact/zip.d.ts
+/** One file of a zip archive, from its central directory. */
+interface ZipEntry {
+  readonly name: string;
+  /**
+   * A name no artifact holds: absolute, with a `..` segment, a backslash or
+   * a NUL. No lookup matches it.
+   */
+  readonly unsafe: boolean;
+  /** A symbolic link, whose data is a path, not a file's bytes. */
+  readonly symlink: boolean;
+  /** 0 stored, 8 deflated. */
+  readonly method: number;
+  readonly compressedSize: number;
+  readonly uncompressedSize: number;
+  readonly localHeaderOffset: number;
+}
+/** Every entry of a zip archive, reading only its central directory. */
+declare const readZipDirectory: (source: ByteSource) => Promise<ZipEntry[]>;
+/**
+ * The one entry an artifact's reader takes by `name`: a symbolic link, or a
+ * name the archive holds twice, which could hand the reader other bytes
+ * than an installer reads, is refused. Unsafe names match nothing.
+ */
+declare const findZipEntry: (entries: readonly ZipEntry[], match: string | ((name: string) => boolean)) => ZipEntry | undefined;
+/**
+ * An entry's uncompressed bytes as a stream, read from the source a chunk at
+ * a time, so a large entry is never held whole.
+ */
+declare const openZipEntry: (source: ByteSource, entry: ZipEntry, { maxBytes }?: {
+  /** The most the entry may inflate to, whatever its header says. */
+  readonly maxBytes?: number;
+}) => Promise<ReadableStream<Uint8Array>>;
+//#endregion
+export { type ByteSource, type ImportableNativeBuild, type NativeArtifactCheck, NativeArtifactError, type NativeArtifactInfo, type NativeArtifactKind, type NativeArtifactProblem, type NativeArtifactProblemCode, type UnreadableValue, type ZipEntry, alreadyImportedProblem, blobSource, checkNativeArtifact, findZipEntry, openZipEntry, readNativeArtifact, readZipDirectory };