Fix StartOS 0.4 TypeScript packaging to match SDK API

2026-04-09 15:10:44 -05:00
parent d5046a0daf
commit 0b70cbb2bf
3436 changed files with 867051 additions and 92 deletions
@@ -0,0 +1,83 @@
+import { DataUrl, Manifest, MerkleArchiveCommitment, PackageId } from '../osBindings';
+import { MerkleArchive } from './merkleArchive';
+/**
+ * Compares two `Uint8Array` instances byte-by-byte for equality.
+ *
+ * @returns `true` if both arrays have the same length and identical bytes
+ */
+export declare function compare(a: Uint8Array, b: Uint8Array): boolean;
+/**
+ * Represents a parsed `.s9pk` package archive — the binary distribution format for StartOS services.
+ *
+ * An `S9pk` wraps a verified {@link Manifest}, a {@link MerkleArchive} containing the package's
+ * assets (icon, license, dependency metadata), and the total archive size in bytes.
+ *
+ * @example
+ * ```ts
+ * const s9pk = await S9pk.deserialize(file, null)
+ * console.log(s9pk.manifest.id)    // e.g. "bitcoind"
+ * console.log(s9pk.size)           // archive size in bytes
+ * const icon = await s9pk.icon()   // base64 data URL
+ * const license = await s9pk.license()
+ * ```
+ */
+export declare class S9pk {
+    /** The parsed package manifest containing metadata, dependencies, and interface definitions. */
+    readonly manifest: Manifest;
+    /** The Merkle-verified archive containing the package's files. */
+    readonly archive: MerkleArchive;
+    /** The total size of the archive in bytes. */
+    readonly size: number;
+    private constructor();
+    /**
+     * Deserializes an `S9pk` from a `Blob` (e.g. a `File` from a browser file input).
+     *
+     * Validates the magic bytes and version header, then parses the Merkle archive structure.
+     * If a `commitment` is provided, the archive is cryptographically verified against it.
+     *
+     * @param source - The raw `.s9pk` file as a `Blob`
+     * @param commitment - An optional Merkle commitment to verify the archive against, or `null` to skip verification
+     * @returns A fully parsed `S9pk` instance
+     * @throws If the magic bytes are invalid or the archive fails verification
+     */
+    static deserialize(source: Blob, commitment: MerkleArchiveCommitment | null): Promise<S9pk>;
+    /**
+     * Extracts the package icon from the archive and returns it as a base64-encoded data URL.
+     *
+     * Looks for a file named `icon.*` with an image MIME type (e.g. `icon.png`, `icon.svg`).
+     *
+     * @returns A data URL string like `"data:image/png;base64,..."` suitable for use in `<img src>`.
+     * @throws If no icon file is found in the archive
+     */
+    icon(): Promise<DataUrl>;
+    /**
+     * Returns the metadata (e.g. `{ title }`) for a specific dependency by its package ID.
+     *
+     * @param id - The dependency's package identifier (e.g. `"bitcoind"`)
+     * @returns The dependency metadata object, or `null` if the dependency is not present in the archive
+     */
+    dependencyMetadataFor(id: PackageId): Promise<{
+        title: string;
+    } | null>;
+    /**
+     * Returns the icon for a specific dependency as a base64 data URL.
+     *
+     * @param id - The dependency's package identifier
+     * @returns A data URL string, or `null` if the dependency or its icon is not present
+     */
+    dependencyIconFor(id: PackageId): Promise<string | null>;
+    /**
+     * Returns a merged record of all dependency metadata (title, icon, description, optional flag)
+     * for every dependency declared in the manifest.
+     *
+     * @returns A record keyed by package ID, each containing `{ title, icon, description, optional }`
+     */
+    dependencyMetadata(): Promise<any>;
+    /**
+     * Reads and returns the `LICENSE.md` file from the archive as a UTF-8 string.
+     *
+     * @returns The full license text
+     * @throws If `LICENSE.md` is not found in the archive
+     */
+    license(): Promise<string>;
+}