npm - @wvb/node - Versions diffs - 0.0.0 - Mend

@wvb/node 0.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/CHANGELOG.md +1 -0
package/README.md +1 -0
package/binding.darwin-arm64.node +0 -0
package/index.cjs +532 -0
package/index.d.cts +1413 -0
package/index.d.ts +1413 -0
package/index.js +533 -0
package/package.json +91 -0
package/wvb-node.darwin-arm64.node +0 -0

package/index.d.ts ADDED Viewed

@@ -0,0 +1,1413 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+/**
+ * A complete bundle including metadata and file data.
+ *
+ * Represents a `.wvb` bundle file loaded entirely into memory.
+ * Use this when you need to access multiple files or build new bundles.
+ *
+ * @example
+ * ```typescript
+ * // Read a bundle from file
+ * const bundle = await readBundle("app.wvb");
+ *
+ * // Access files
+ * const html = bundle.getData("/index.html");
+ * if (html) {
+ *   console.log(html.toString("utf-8"));
+ * }
+ * ```
+ */
+export declare class Bundle {
+  /**
+   * Returns the bundle descriptor (header and index).
+   *
+   * @returns {BundleDescriptor} Bundle metadata
+   *
+   * @example
+   * ```typescript
+   * const descriptor = bundle.descriptor();
+   * const index = descriptor.index();
+   * ```
+   */
+  descriptor(): BundleDescriptor
+  /**
+   * Retrieves file data by path.
+   *
+   * Returns the decompressed file contents, or null if the path doesn't exist.
+   *
+   * @param {string} path - File path in the bundle (e.g., "/index.html")
+   * @returns {Buffer | null} File contents or null if not found
+   *
+   * @example
+   * ```typescript
+   * const data = bundle.getData("/index.html");
+   * if (data) {
+   *   console.log(data.toString("utf-8"));
+   * }
+   * ```
+   */
+  getData(path: string): Buffer | null
+  /**
+   * Retrieves the checksum of file data by path.
+   *
+   * @param {string} path - File path in the bundle
+   * @returns {number | null} xxHash-32 checksum or null if not found
+   */
+  getDataChecksum(path: string): number | null
+}
+/**
+ * Builder for creating bundle files.
+ *
+ * Allows you to add files, set options, and generate a complete bundle.
+ *
+ * @example
+ * ```typescript
+ * const builder = new BundleBuilder();
+ *
+ * // Add files
+ * builder.insertEntry("/index.html", Buffer.from("<html>...</html>"));
+ * builder.insertEntry("/app.js", Buffer.from("console.log('hello');"));
+ *
+ * // Build the bundle
+ * const bundle = builder.build();
+ *
+ * // Write to file
+ * await writeBundle(bundle, "app.wvb");
+ * ```
+ */
+export declare class BundleBuilder {
+  /**
+   * Creates a new bundle builder.
+   *
+   * @param {Version} [version] - Bundle format version (defaults to V1)
+   *
+   * @example
+   * ```typescript
+   * const builder = new BundleBuilder();
+   * ```
+   */
+  constructor(version?: Version | undefined | null)
+  /**
+   * Gets the bundle format version.
+   *
+   * @returns {Version} Bundle format version
+   */
+  get version(): Version
+  /**
+   * Returns all entry paths currently in the builder.
+   *
+   * @returns {string[]} Array of file paths
+   *
+   * @example
+   * ```typescript
+   * const paths = builder.entryPaths();
+   * console.log(paths); // ["/index.html", "/app.js"]
+   * ```
+   */
+  entryPaths(): Array<string>
+  /**
+   * Adds or updates a file in the bundle.
+   *
+   * If `contentType` is not provided, it will be auto-detected from the file
+   * extension and content.
+   *
+   * @param {string} path - File path (must start with "/")
+   * @param {Buffer} data - File contents
+   * @param {string} [contentType] - MIME type (auto-detected if not provided)
+   * @param {Record<string, string>} [headers] - Optional HTTP headers
+   * @returns {boolean} True if a file was replaced, false if newly added
+   *
+   * @example
+   * ```typescript
+   * // Auto-detect MIME type
+   * builder.insertEntry("/index.html", Buffer.from("<html></html>"));
+   *
+   * // Specify MIME type
+   * builder.insertEntry("/data.bin", buffer, "application/octet-stream");
+   *
+   * // With custom headers
+   * builder.insertEntry("/style.css", cssBuffer, "text/css", {
+   *   "Cache-Control": "max-age=3600"
+   * });
+   * ```
+   */
+  insertEntry(path: string, data: Buffer, contentType?: string | undefined | null, headers?: Record<string, string> | undefined | null): boolean
+  /**
+   * Removes a file from the bundle.
+   *
+   * @param {string} path - File path to remove
+   * @returns {boolean} True if the file was removed, false if not found
+   *
+   * @example
+   * ```typescript
+   * builder.removeEntry("/old-file.js");
+   * ```
+   */
+  removeEntry(path: string): boolean
+  /**
+   * Checks if a file path exists in the builder.
+   *
+   * @param {string} path - File path to check
+   * @returns {boolean} True if the path exists
+   *
+   * @example
+   * ```typescript
+   * if (builder.containsEntry("/index.html")) {
+   *   console.log("index.html already added");
+   * }
+   * ```
+   */
+  containsEntry(path: string): boolean
+  /**
+   * Builds the bundle with all added files.
+   *
+   * This consumes the builder's entries and creates a complete bundle with
+   * compressed data.
+   *
+   * @param {BuildOptions} [options] - Build options
+   * @returns {Bundle} The built bundle
+   *
+   * @example
+   * ```typescript
+   * const bundle = builder.build();
+   * await writeBundle(bundle, "output.wvb");
+   * ```
+   */
+  build(options?: BuildOptions | undefined | null): Bundle
+}
+/**
+ * Bundle metadata including header and index information.
+ *
+ * A descriptor contains only the metadata without loading the actual file data,
+ * making it efficient for inspecting bundle contents.
+ *
+ * @example
+ * ```typescript
+ * const bundle = await readBundle("app.wvb");
+ * const descriptor = bundle.descriptor();
+ * const header = descriptor.header();
+ * const index = descriptor.index();
+ * ```
+ */
+export declare class BundleDescriptor {
+  /**
+   * Returns the bundle header.
+   *
+   * @returns {Header} Bundle header with format metadata
+   */
+  header(): Header
+  /**
+   * Returns the bundle index.
+   *
+   * @returns {Index} Bundle index with file metadata
+   */
+  index(): Index
+}
+/**
+ * Protocol handler for serving files from bundle sources.
+ *
+ * Serves web resources from `.wvb` bundle files, supporting:
+ * - GET and HEAD HTTP methods
+ * - HTTP Range requests for streaming
+ * - Content-Type and custom HTTP headers
+ *
+ * @example
+ * ```typescript
+ * const source = new BundleSource({
+ *   builtinDir: "./bundles/builtin",
+ *   remoteDir: "./bundles/remote"
+ * });
+ *
+ * const protocol = new BundleProtocol(source);
+ *
+ * // Handle a request
+ * const response = await protocol.handle("GET", "bundle://app/index.html");
+ * console.log(`Status: ${response.status}`);
+ * console.log(`Content-Type: ${response.headers["content-type"]}`);
+ * ```
+ */
+export declare class BundleProtocol {
+  /**
+   * Creates a new bundle protocol handler.
+   *
+   * @param {BundleSource} source - Bundle source to serve files from
+   *
+   * @example
+   * ```typescript
+   * const source = new BundleSource({
+   *   builtinDir: "./bundles",
+   *   remoteDir: "./remote"
+   * });
+   * const protocol = new BundleProtocol(source);
+   * ```
+   */
+  constructor(source: BundleSource)
+  /**
+   * Handles an HTTP request and returns a response.
+   *
+   * Processes requests in the format `scheme://bundle_name/path/to/file`.
+   *
+   * @param {HttpMethod} method - HTTP method (GET or HEAD)
+   * @param {string} uri - Request URI (e.g., "bundle://app/index.html")
+   * @param {Record<string, string>} [headers] - Optional request headers
+   * @returns {Promise<HttpResponse>} HTTP response
+   *
+   * @example
+   * ```typescript
+   * // GET request
+   * const response = await protocol.handle("GET", "bundle://app/index.html");
+   * if (response.status === 200) {
+   *   console.log(response.body.toString("utf-8"));
+   * }
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // Range request for streaming
+   * const response = await protocol.handle(
+   *   "GET",
+   *   "bundle://app/video.mp4",
+   *   { "Range": "bytes=0-1023" }
+   * );
+   * console.log(`Status: ${response.status}`); // 206 Partial Content
+   * ```
+   */
+  handle(method: HttpMethod, uri: string, headers?: Record<string, string> | undefined | null): Promise<HttpResponse>
+}
+/**
+ * Bundle source for managing multiple bundle versions.
+ *
+ * A source manages bundles in two directories:
+ * - **builtin**: Bundles shipped with the app (read-only, fallback)
+ * - **remote**: Downloaded bundles (takes priority)
+ *
+ * The source automatically handles version selection, with remote bundles
+ * taking priority over builtin ones.
+ *
+ * @example
+ * ```typescript
+ * const source = new BundleSource({
+ *   builtinDir: "./bundles/builtin",
+ *   remoteDir: "./bundles/remote"
+ * });
+ *
+ * // List all bundles
+ * const bundles = await source.listBundles();
+ *
+ * // Load current version
+ * const version = await source.loadVersion("app");
+ *
+ * // Fetch bundle
+ * const bundle = await source.fetch("app");
+ * ```
+ */
+export declare class BundleSource {
+  /**
+   * Creates a new bundle source.
+   *
+   * @param {BundleSourceConfig} config - Source configuration
+   *
+   * @example
+   * ```typescript
+   * const source = new BundleSource({
+   *   builtinDir: "./builtin",
+   *   remoteDir: "./remote"
+   * });
+   * ```
+   */
+  constructor(config: BundleSourceConfig)
+  /**
+   * Lists all available bundles from both sources.
+   *
+   * Returns bundles from both builtin and remote directories, including
+   * all versions and metadata.
+   *
+   * @returns {Promise<ListBundleItem[]>} List of bundle items
+   *
+   * @example
+   * ```typescript
+   * const bundles = await source.listBundles();
+   * for (const bundle of bundles) {
+   *   console.log(`${bundle.name}@${bundle.version} (${bundle.type})`);
+   * }
+   * ```
+   */
+  listBundles(): Promise<Array<ListBundleItem>>
+  /**
+   * Loads the current version for a bundle.
+   *
+   * Returns the version from remote if available, otherwise from builtin.
+   *
+   * @param {string} bundleName - Name of the bundle
+   * @returns {Promise<BundleSourceVersion | null>} Version info or null if not found
+   *
+   * @example
+   * ```typescript
+   * const version = await source.loadVersion("app");
+   * if (version) {
+   *   console.log(`Current version: ${version.version} (${version.type})`);
+   * }
+   * ```
+   */
+  loadVersion(bundleName: string): Promise<BundleSourceVersion | null>
+  /**
+   * Updates the current version for a bundle.
+   *
+   * Changes which version is considered "current" in the manifest.
+   *
+   * @param {string} bundleName - Name of the bundle
+   * @param {string} version - Version to set as current
+   *
+   * @example
+   * ```typescript
+   * await source.updateVersion("app", "1.2.0");
+   * ```
+   */
+  updateVersion(bundleName: string, version: string): Promise<void>
+  /**
+   * Gets the file path for a bundle.
+   *
+   * Returns the path to the `.wvb` file for the current version,
+   * preferring remote over builtin.
+   *
+   * @param {string} bundleName - Name of the bundle
+   * @returns {Promise<string>} Absolute file path
+   *
+   * @example
+   * ```typescript
+   * const path = await source.filepath("app");
+   * console.log(`Bundle at: ${path}`);
+   * ```
+   */
+  filepath(bundleName: string): Promise<string>
+  /**
+   * Fetches and loads a bundle.
+   *
+   * Loads the entire bundle into memory for the current version.
+   *
+   * @param {string} bundleName - Name of the bundle
+   * @returns {Promise<Bundle>} Loaded bundle
+   *
+   * @example
+   * ```typescript
+   * const bundle = await source.fetch("app");
+   * const html = bundle.getData("/index.html");
+   * ```
+   */
+  fetch(bundleName: string): Promise<Bundle>
+  /**
+   * Fetches only the bundle descriptor (metadata).
+   *
+   * Loads only header and index without file data, useful for inspection.
+   *
+   * @param {string} bundleName - Name of the bundle
+   * @returns {Promise<BundleDescriptor>} Bundle descriptor
+   *
+   * @example
+   * ```typescript
+   * const descriptor = await source.fetchDescriptor("app");
+   * const index = descriptor.index();
+   * console.log(`Files: ${Object.keys(index.entries()).length}`);
+   * ```
+   */
+  fetchDescriptor(bundleName: string): Promise<BundleDescriptor>
+  /**
+   * Writes a bundle to the remote directory.
+   *
+   * Installs a new bundle version to the remote directory and updates
+   * the manifest.
+   *
+   * @param {string} bundleName - Name of the bundle
+   * @param {string} version - Version string
+   * @param {Bundle} bundle - Bundle to write
+   * @param {BundleManifestMetadata} metadata - Bundle metadata
+   *
+   * @example
+   * ```typescript
+   * await source.writeRemoteBundle("app", "1.2.0", bundle, {
+   *   integrity: "sha3-384-...",
+   *   etag: "abc123"
+   * });
+   * ```
+   */
+  writeRemoteBundle(bundleName: string, version: string, bundle: Bundle, metadata: BundleManifestMetadata): Promise<void>
+}
+/**
+ * Bundle header containing format metadata.
+ *
+ * The header is the first 17 bytes of a `.wvb` file and includes:
+ * - Magic number (🌐🎁)
+ * - Format version
+ * - Index size
+ * - Header checksum
+ */
+export declare class Header {
+  /**
+   * Returns the bundle format version.
+   *
+   * @returns {Version} The format version (e.g., V1)
+   *
+   * @example
+   * ```typescript
+   * const header = bundle.descriptor().header();
+   * console.log(header.version()); // Version.V1
+   * ```
+   */
+  version(): Version
+  /**
+   * Returns the byte offset where the index section ends.
+   *
+   * This marks the start of the data section.
+   *
+   * @returns {bigint} Byte offset
+   */
+  indexEndOffset(): bigint
+  /**
+   * Returns the size of the index section in bytes.
+   *
+   * @returns {number} Index size in bytes
+   */
+  indexSize(): number
+}
+/**
+ * Bundle index mapping file paths to their metadata.
+ *
+ * The index is stored as binary data in the bundle file and maps file paths
+ * to their metadata (offset, length, content-type, headers, etc.).
+ */
+export declare class Index {
+  /**
+   * Returns all index entries as a map of path to metadata.
+   *
+   * @returns {Record<string, IndexEntry>} Map of file paths to entry metadata
+   *
+   * @example
+   * ```typescript
+   * const index = bundle.descriptor().index();
+   * const entries = index.entries();
+   * for (const [path, entry] of Object.entries(entries)) {
+   *   console.log(`${path}: ${entry.contentType}`);
+   * }
+   * ```
+   */
+  entries(): Record<string, IndexEntry>
+  /**
+   * Gets the index entry for a specific file path.
+   *
+   * @param {string} path - File path in the bundle (e.g., "/index.html")
+   * @returns {IndexEntry | null} Entry metadata or null if not found
+   *
+   * @example
+   * ```typescript
+   * const entry = index.getEntry("/index.html");
+   * if (entry) {
+   *   console.log(`Content-Type: ${entry.contentType}`);
+   * }
+   * ```
+   */
+  getEntry(path: string): IndexEntry | null
+  /**
+   * Checks if a file path exists in the bundle.
+   *
+   * @param {string} path - File path to check
+   * @returns {boolean} True if the path exists
+   *
+   * @example
+   * ```typescript
+   * if (index.containsPath("/app.js")) {
+   *   console.log("app.js is in the bundle");
+   * }
+   * ```
+   */
+  containsPath(path: string): boolean
+}
+/**
+ * Protocol handler that proxies requests to localhost servers.
+ *
+ * Forwards requests to local development servers for hot-reloading workflows.
+ * Features response caching and 304 Not Modified support.
+ *
+ * @example
+ * ```typescript
+ * const protocol = new LocalProtocol({
+ *   "myapp": "http://localhost:3000",
+ *   "api": "http://localhost:8080"
+ * });
+ *
+ * // This proxies to http://localhost:3000/index.html
+ * const response = await protocol.handle("GET", "app://myapp/index.html");
+ * ```
+ */
+export declare class LocalProtocol {
+  /**
+   * Creates a new local protocol handler.
+   *
+   * @param {Record<string, string>} hosts - Map of custom hosts to localhost URLs
+   *
+   * @example
+   * ```typescript
+   * const protocol = new LocalProtocol({
+   *   "myapp": "http://localhost:3000",
+   *   "api": "http://localhost:8080"
+   * });
+   * ```
+   */
+  constructor(hosts: Record<string, string>)
+  /**
+   * Handles an HTTP request by proxying to localhost.
+   *
+   * Maps custom protocol URIs to localhost URLs and forwards the request.
+   *
+   * @param {HttpMethod} method - HTTP method
+   * @param {string} uri - Request URI (e.g., "app://myapp/api/data")
+   * @param {Record<string, string>} [headers] - Optional request headers
+   * @returns {Promise<HttpResponse>} HTTP response from localhost
+   *
+   * @example
+   * ```typescript
+   * // Proxies to http://localhost:3000/api/data?foo=bar
+   * const response = await protocol.handle(
+   *   "GET",
+   *   "app://myapp/api/data?foo=bar"
+   * );
+   * console.log(response.status);
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // POST with headers
+   * const response = await protocol.handle(
+   *   "POST",
+   *   "app://api/submit",
+   *   { "Content-Type": "application/json" }
+   * );
+   * ```
+   */
+  handle(method: HttpMethod, uri: string, headers?: Record<string, string> | undefined | null): Promise<HttpResponse>
+}
+/**
+ * HTTP client for downloading bundles from a remote server.
+ *
+ * The remote client implements the bundle HTTP protocol, allowing you to:
+ * - List available bundles
+ * - Get bundle metadata
+ * - Download specific versions
+ * - Track download progress
+ *
+ * @example
+ * ```typescript
+ * const remote = new Remote("https://updates.example.com");
+ *
+ * // List all bundles
+ * const bundles = await remote.listBundles();
+ *
+ * // Get current version info
+ * const info = await remote.getInfo("app");
+ * console.log(`Latest version: ${info.version}`);
+ *
+ * // Download bundle
+ * const [bundleInfo, bundle, data] = await remote.download("app");
+ * ```
+ */
+export declare class Remote {
+  /**
+   * Creates a new remote client.
+   *
+   * @param {string} endpoint - Base URL of the remote server
+   * @param {RemoteOptions} [options] - Client options
+   *
+   * @example
+   * ```typescript
+   * const remote = new Remote("https://updates.example.com");
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // With options
+   * const remote = new Remote("https://updates.example.com", {
+   *   http: { timeout: 60000 },
+   *   onDownload: (data) => {
+   *     const percent = (data.downloadedBytes / data.totalBytes) * 100;
+   *     console.log(`Progress: ${percent.toFixed(1)}%`);
+   *   }
+   * });
+   * ```
+   */
+  constructor(endpoint: string, options?: RemoteOptions | undefined | null)
+  /**
+   * Lists all available bundles on the server.
+   *
+   * @param {string} [channel] - Optional channel filter
+   * @returns {Promise<ListRemoteBundleInfo[]>} List of bundles
+   *
+   * @example
+   * ```typescript
+   * const bundles = await remote.listBundles();
+   * for (const bundle of bundles) {
+   *   console.log(`${bundle.name}@${bundle.version}`);
+   * }
+   * ```
+   */
+  listBundles(channel?: string | undefined | null): Promise<Array<ListRemoteBundleInfo>>
+  /**
+   * Gets bundle metadata for the current version.
+   *
+   * Fetches metadata without downloading the bundle itself.
+   *
+   * @param {string} bundleName - Name of the bundle
+   * @param {string} [channel] - Optional channel filter
+   * @returns {Promise<RemoteBundleInfo>} Bundle information
+   *
+   * @example
+   * ```typescript
+   * const info = await remote.getInfo("app");
+   * console.log(`Current version: ${info.version}`);
+   * if (info.integrity) {
+   *   console.log(`Integrity: ${info.integrity}`);
+   * }
+   * ```
+   */
+  getInfo(bundleName: string, channel?: string | undefined | null): Promise<RemoteBundleInfo>
+  /**
+   * Downloads the current version of a bundle.
+   *
+   * Returns bundle info, parsed bundle, and raw data.
+   *
+   * @param {string} bundleName - Name of the bundle
+   * @param {string} [channel] - Optional channel filter
+   * @returns {Promise<[RemoteBundleInfo, Bundle, Buffer]>} Tuple of info, bundle, and data
+   *
+   * @example
+   * ```typescript
+   * const [info, bundle, data] = await remote.download("app");
+   * console.log(`Downloaded ${info.name}@${info.version}`);
+   * console.log(`Size: ${data.length} bytes`);
+   *
+   * // Save to file
+   * await writeBundle(bundle, "app.wvb");
+   * ```
+   */
+  download(bundleName: string, channel?: string | undefined | null): Promise<[RemoteBundleInfo, Bundle, Buffer]>
+  /**
+   * Downloads a specific version of a bundle.
+   *
+   * @param {string} bundleName - Name of the bundle
+   * @param {string} version - Specific version to download
+   * @returns {Promise<[RemoteBundleInfo, Bundle, Buffer]>} Tuple of info, bundle, and data
+   *
+   * @example
+   * ```typescript
+   * const [info, bundle, data] = await remote.downloadVersion("app", "1.0.0");
+   * console.log(`Downloaded specific version: ${info.version}`);
+   * ```
+   */
+  downloadVersion(bundleName: string, version: string): Promise<[RemoteBundleInfo, Bundle, Buffer]>
+}
+/**
+ * Bundle updater for managing updates from a remote server.
+ *
+ * The updater coordinates between a local bundle source and remote server,
+ * handling update checks, downloads, integrity verification, and signature validation.
+ *
+ * @example
+ * ```typescript
+ * import { Updater, BundleSource, Remote, IntegrityPolicy, SignatureAlgorithm, VerifyingKeyFormat } from "@wvb/node";
+ *
+ * const source = new BundleSource({
+ *   builtinDir: "./bundles/builtin",
+ *   remoteDir: "./bundles/remote"
+ * });
+ *
+ * const remote = new Remote("https://updates.example.com");
+ *
+ * const updater = new Updater(source, remote, {
+ *   channel: "stable",
+ *   integrityPolicy: IntegrityPolicy.Strict,
+ *   signatureVerifier: {
+ *     algorithm: SignatureAlgorithm.Ed25519,
+ *     key: {
+ *       format: VerifyingKeyFormat.SpkiPem,
+ *       data: publicKeyPem
+ *     }
+ *   }
+ * });
+ *
+ * // Check for updates
+ * const updateInfo = await updater.getUpdate("app");
+ * if (updateInfo.isAvailable) {
+ *   console.log(`Update available: ${updateInfo.version}`);
+ *   await updater.downloadUpdate("app");
+ * }
+ * ```
+ */
+export declare class Updater {
+  /**
+   * Creates a new updater instance.
+   *
+   * @param {BundleSource} source - Bundle source for storing downloaded bundles
+   * @param {Remote} remote - Remote client for fetching bundles
+   * @param {UpdaterOptions} [options] - Optional updater configuration
+   *
+   * @example
+   * ```typescript
+   * const updater = new Updater(source, remote, {
+   *   channel: "stable",
+   *   integrityPolicy: IntegrityPolicy.Strict
+   * });
+   * ```
+   */
+  constructor(source: BundleSource, remote: Remote, options?: UpdaterOptions | undefined | null)
+  /**
+   * Lists all available bundles on the remote server.
+   *
+   * @returns {Promise<ListRemoteBundleInfo[]>} Array of remote bundle information
+   *
+   * @example
+   * ```typescript
+   * const remotes = await updater.listRemotes();
+   * for (const bundle of remotes) {
+   *   console.log(`${bundle.name}: ${bundle.version}`);
+   * }
+   * ```
+   */
+  listRemotes(): Promise<Array<ListRemoteBundleInfo>>
+  /**
+   * Checks if an update is available for a specific bundle.
+   *
+   * Compares the local version with the remote version to determine if an update exists.
+   *
+   * @param {string} bundleName - Name of the bundle to check
+   * @returns {Promise<BundleUpdateInfo>} Update information
+   *
+   * @example
+   * ```typescript
+   * const updateInfo = await updater.getUpdate("app");
+   * if (updateInfo.isAvailable) {
+   *   console.log(`Update available: ${updateInfo.localVersion} → ${updateInfo.version}`);
+   * } else {
+   *   console.log("Already up to date");
+   * }
+   * ```
+   */
+  getUpdate(bundleName: string): Promise<BundleUpdateInfo>
+  /**
+   * Downloads and installs a bundle update.
+   *
+   * Downloads the specified bundle version (or the latest if not specified),
+   * verifies integrity and signature if configured, and installs it to the remote directory.
+   *
+   * @param {string} bundleName - Name of the bundle to download
+   * @param {string} [version] - Specific version to download (defaults to latest)
+   * @returns {Promise<RemoteBundleInfo>} Information about the downloaded bundle
+   *
+   * @example
+   * ```typescript
+   * // Download latest version
+   * const info = await updater.downloadUpdate("app");
+   * console.log(`Downloaded ${info.name} v${info.version}`);
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // Download specific version
+   * const info = await updater.downloadUpdate("app", "1.2.3");
+   * console.log(`Downloaded ${info.name} v${info.version}`);
+   * ```
+   */
+  downloadUpdate(bundleName: string, version?: string | undefined | null): Promise<RemoteBundleInfo>
+}
+/**
+ * Options for bundle header generation.
+ *
+ * @property {number} [checksumSeed] - Seed for header checksum (for testing)
+ */
+export interface BuildHeaderOptions {
+  checksumSeed?: number
+}
+/**
+ * Options for bundle index generation.
+ *
+ * @property {number} [checksumSeed] - Seed for index checksum (for testing)
+ */
+export interface BuildIndexOptions {
+  checksumSeed?: number
+}
+/**
+ * Options for building a bundle.
+ *
+ * @property {BuildHeaderOptions} [header] - Header generation options
+ * @property {BuildIndexOptions} [index] - Index generation options
+ * @property {number} [dataChecksumSeed] - Seed for data checksums (for testing)
+ */
+export interface BuildOptions {
+  header?: BuildHeaderOptions
+  index?: BuildIndexOptions
+  dataChecksumSeed?: number
+}
+/**
+ * Complete manifest data structure.
+ *
+ * The manifest tracks all bundle versions and metadata.
+ *
+ * @property {1} manifestVersion - Manifest format version (always 1)
+ * @property {Record<string, BundleManifestEntry>} entries - Bundle entries by name
+ */
+export interface BundleManifestData {
+  manifestVersion: 1
+  entries: Record<string, BundleManifestEntry>
+}
+/**
+ * Entry for a single bundle in the manifest.
+ *
+ * Contains all versions and the current active version.
+ *
+ * @property {Record<string, BundleManifestMetadata>} versions - Available versions
+ * @property {string} currentVersion - Currently active version
+ */
+export interface BundleManifestEntry {
+  versions: Record<string, BundleManifestMetadata>
+  currentVersion: string
+}
+/**
+ * Metadata for a bundle version in the manifest.
+ *
+ * Contains cache validation and integrity information.
+ *
+ * @property {string} [etag] - HTTP ETag for cache validation
+ * @property {string} [integrity] - SHA3 integrity hash for verification
+ * @property {string} [signature] - Digital signature for authentication
+ * @property {string} [lastModified] - HTTP Last-Modified timestamp
+ */
+export interface BundleManifestMetadata {
+  etag?: string
+  integrity?: string
+  signature?: string
+  lastModified?: string
+}
+/**
+ * Manifest format version.
+ *
+ * @enum {number}
+ */
+export declare enum BundleManifestVersion {
+  V1 = 1
+}
+/**
+ * Configuration for creating a bundle source.
+ *
+ * @property {string} builtinDir - Directory containing builtin bundles
+ * @property {string} remoteDir - Directory containing remote bundles
+ * @property {string} [builtinManifestFilepath] - Custom manifest path for builtin
+ * @property {string} [remoteManifestFilepath] - Custom manifest path for remote
+ *
+ * @example
+ * ```typescript
+ * const config = {
+ *   builtinDir: "./bundles/builtin",
+ *   remoteDir: "./bundles/remote"
+ * };
+ * const source = new BundleSource(config);
+ * ```
+ */
+export interface BundleSourceConfig {
+  builtinDir: string
+  remoteDir: string
+  builtinManifestFilepath?: string
+  remoteManifestFilepath?: string
+}
+/**
+ * The type of bundle source: builtin or remote.
+ *
+ * @enum {string}
+ */
+export type BundleSourceKind = /** Bundles shipped with the application (read-only| fallback) */
+'builtin'|
+/** Downloaded bundles (takes priority over builtin) */
+'remote';
+/**
+ * Bundle version with source kind information.
+ *
+ * Indicates which source (builtin or remote) provides a bundle version.
+ *
+ * @property {BundleSourceKind} type - The source kind
+ * @property {string} version - The version string (e.g., "1.0.0")
+ */
+export interface BundleSourceVersion {
+  type: BundleSourceKind
+  version: string
+}
+/**
+ * Information about a bundle update.
+ *
+ * @property {string} name - Bundle name
+ * @property {string} version - Remote version available
+ * @property {string} [localVersion] - Currently installed version
+ * @property {boolean} isAvailable - Whether an update is available
+ * @property {string} [etag] - ETag for caching
+ * @property {string} [integrity] - Integrity hash (e.g., "sha384-...")
+ * @property {string} [signature] - Digital signature
+ * @property {string} [lastModified] - Last modified timestamp
+ *
+ * @example
+ * ```typescript
+ * const updateInfo = await updater.getUpdate("app");
+ * if (updateInfo.isAvailable) {
+ *   console.log(`Update available: ${updateInfo.localVersion} → ${updateInfo.version}`);
+ *   await updater.downloadUpdate("app");
+ * }
+ * ```
+ */
+export interface BundleUpdateInfo {
+  name: string
+  version: string
+  localVersion?: string
+  isAvailable: boolean
+  etag?: string
+  integrity?: string
+  signature?: string
+  lastModified?: string
+}
+export type HttpMethod =  'get'|
+'head'|
+'options'|
+'post'|
+'put'|
+'patch'|
+'delete'|
+'trace'|
+'connect';
+export interface HttpOptions {
+  defaultHeaders?: Record<string, string>
+  userAgent?: string
+  timeout?: number
+  readTimeout?: number
+  connectTimeout?: number
+  poolIdleTimeout?: number
+  poolMaxIdlePerHost?: number
+  referer?: boolean
+  tcpNodelay?: boolean
+  hickoryDns?: boolean
+}
+export interface HttpResponse {
+  status: number
+  headers: Record<string, string>
+  body: Buffer
+}
+/**
+ * Metadata for a single file in the bundle.
+ *
+ * Contains information about file location, size, MIME type, and HTTP headers.
+ *
+ * @property {number} offset - Byte offset in the data section (compressed)
+ * @property {number} len - Length of compressed data in bytes
+ * @property {boolean} isEmpty - Whether the compressed data is empty
+ * @property {string} contentType - MIME type of the file
+ * @property {number} contentLength - Original file size before compression
+ * @property {Record<string, string>} headers - HTTP headers for this file
+ */
+export interface IndexEntry {
+  offset: number
+  len: number
+  isEmpty: boolean
+  contentType: string
+  contentLength: number
+  headers: Record<string, string>
+}
+/**
+ * Hash algorithm for bundle integrity verification.
+ *
+ * Supports SHA-2 family hash algorithms for cryptographic verification
+ * following the Subresource Integrity specification.
+ *
+ * @example
+ * ```typescript
+ * // Integrity strings use these algorithms:
+ * // "sha256-abc123..." - SHA-256
+ * // "sha384-def456..." - SHA-384 (recommended)
+ * // "sha512-ghi789..." - SHA-512
+ * ```
+ */
+export type IntegrityAlgorithm = /** SHA-256 (256-bit hash) */
+'sha256'|
+/** SHA-384 (384-bit hash| recommended) */
+'sha384'|
+/** SHA-512 (512-bit hash) */
+'sha512';
+/**
+ * Policy for enforcing integrity verification during bundle operations.
+ *
+ * Controls when integrity hashes are required and how missing hashes are handled.
+ *
+ * @example
+ * ```typescript
+ * import { Updater, IntegrityPolicy } from "@wvb/node";
+ *
+ * // Require integrity for all bundles
+ * const updater = new Updater(source, remote, {
+ *   integrityPolicy: IntegrityPolicy.Strict
+ * });
+ *
+ * // Optional integrity (warn if missing)
+ * const updater2 = new Updater(source, remote, {
+ *   integrityPolicy: IntegrityPolicy.Optional
+ * });
+ * ```
+ */
+export type IntegrityPolicy = /** Require integrity verification for all bundles. Operations fail if integrity is missing or invalid. */
+'strict'|
+/** Verify integrity if provided| but allow operations without it. */
+'optional'|
+/** Skip integrity verification entirely. */
+'none';
+/**
+ * Information about a bundle from list operations.
+ *
+ * @property {BundleSourceKind} type - Source kind (builtin or remote)
+ * @property {string} name - Bundle name
+ * @property {string} version - Version string
+ * @property {boolean} current - Whether this is the current active version
+ * @property {BundleManifestMetadata} metadata - Bundle metadata
+ */
+export interface ListBundleItem {
+  type: BundleSourceKind
+  name: string
+  version: string
+  current: boolean
+  metadata: BundleManifestMetadata
+}
+/**
+ * Bundle information from list operations.
+ *
+ * @property {string} name - Bundle name
+ * @property {string} version - Version string
+ */
+export interface ListRemoteBundleInfo {
+  name: string
+  version: string
+}
+/**
+ * Reads a bundle from a file asynchronously.
+ *
+ * @param {string} filepath - Path to the `.wvb` file
+ * @returns {Promise<Bundle>} Parsed bundle
+ * @throws {Error} If the file cannot be read or is not a valid bundle
+ *
+ * @example
+ * ```typescript
+ * const bundle = await readBundle("app.wvb");
+ * const html = bundle.getData("/index.html");
+ * ```
+ */
+export declare function readBundle(filepath: string): Promise<Bundle>
+/**
+ * Reads a bundle from a buffer synchronously.
+ *
+ * @param {Buffer} buffer - Buffer containing bundle data
+ * @returns {Bundle} Parsed bundle
+ * @throws {Error} If the buffer is not a valid bundle
+ *
+ * @example
+ * ```typescript
+ * import { readFileSync } from "fs";
+ * const buffer = readFileSync("app.wvb");
+ * const bundle = readBundleFromBuffer(buffer);
+ * ```
+ */
+export declare function readBundleFromBuffer(buffer: Buffer): Bundle
+/**
+ * Complete bundle information from remote server.
+ *
+ * Contains version, cache validation, and integrity data.
+ *
+ * @property {string} name - Bundle name
+ * @property {string} version - Version string
+ * @property {string} [etag] - HTTP ETag for cache validation
+ * @property {string} [integrity] - SHA3 integrity hash
+ * @property {string} [signature] - Digital signature
+ * @property {string} [lastModified] - Last-Modified timestamp
+ */
+export interface RemoteBundleInfo {
+  name: string
+  version: string
+  etag?: string
+  integrity?: string
+  signature?: string
+  lastModified?: string
+}
+/**
+ * Download progress data.
+ *
+ * @property {number} downloadedBytes - Bytes downloaded so far
+ * @property {number} totalBytes - Total bytes to download
+ * @property {string} endpoint - Endpoint being downloaded from
+ */
+export interface RemoteOnDownloadData {
+  downloadedBytes: number
+  totalBytes: number
+  endpoint: string
+}
+/**
+ * Options for creating a remote client.
+ *
+ * @property {HttpOptions} [http] - HTTP client configuration
+ * @property {(data: RemoteOnDownloadData) => void} [onDownload] - Download progress callback
+ *
+ * @example
+ * ```typescript
+ * const options = {
+ *   http: { timeout: 30000 },
+ *   onDownload: (data) => {
+ *     console.log(`Downloaded ${data.downloadedBytes}/${data.totalBytes}`);
+ *   }
+ * };
+ * const remote = new Remote("https://updates.example.com", options);
+ * ```
+ */
+export interface RemoteOptions {
+  http?: HttpOptions
+  onDownload?: (data: RemoteOnDownloadData) => void
+}
+/**
+ * Digital signature algorithm for bundle verification.
+ *
+ * Supports multiple signature schemes for cryptographic verification of bundle authenticity.
+ *
+ * @example
+ * ```typescript
+ * import { Updater, SignatureAlgorithm, VerifyingKeyFormat } from "@wvb/node";
+ *
+ * const updater = new Updater(source, remote, {
+ *   signatureVerifier: {
+ *     algorithm: SignatureAlgorithm.Ed25519,
+ *     key: {
+ *       format: VerifyingKeyFormat.SpkiPem,
+ *       data: "-----BEGIN PUBLIC KEY-----
+...
+-----END PUBLIC KEY-----"
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export type SignatureAlgorithm = /** ECDSA with P-256 curve (secp256r1) */
+'ecdsaSecp256R1'|
+/** ECDSA with P-384 curve (secp384r1) */
+'ecdsaSecp384R1'|
+/** Ed25519 (EdDSA| recommended for modern applications) */
+'ed25519'|
+/** RSA PKCS#1 v1.5 signature scheme */
+'rsaPkcs1V15'|
+/** RSA-PSS (Probabilistic Signature Scheme) */
+'rsaPss';
+/**
+ * Configuration for signature verification.
+ *
+ * @property {SignatureAlgorithm} algorithm - The signature algorithm to use
+ * @property {SignatureVerifyingKeyOptions} key - The public key configuration
+ *
+ * @example
+ * ```typescript
+ * const verifierOptions = {
+ *   algorithm: SignatureAlgorithm.Ed25519,
+ *   key: {
+ *     format: VerifyingKeyFormat.SpkiPem,
+ *     data: "-----BEGIN PUBLIC KEY-----
+...
+-----END PUBLIC KEY-----"
+ *   }
+ * };
+ * ```
+ */
+export interface SignatureVerifierOptions {
+  algorithm: SignatureAlgorithm
+  key: SignatureVerifyingKeyOptions
+}
+/**
+ * Public key configuration for signature verification.
+ *
+ * @property {VerifyingKeyFormat} format - The format of the public key
+ * @property {string | Uint8Array} data - The key data (string for PEM, Uint8Array for DER/Raw)
+ *
+ * @example
+ * ```typescript
+ * // PEM format (string)
+ * const pemKey = {
+ *   format: VerifyingKeyFormat.SpkiPem,
+ *   data: "-----BEGIN PUBLIC KEY-----
+...
+-----END PUBLIC KEY-----"
+ * };
+ *
+ * // DER format (binary)
+ * const derKey = {
+ *   format: VerifyingKeyFormat.SpkiDer,
+ *   data: new Uint8Array([...])
+ * };
+ * ```
+ */
+export interface SignatureVerifyingKeyOptions {
+  format: VerifyingKeyFormat
+  data: string | Uint8Array
+}
+/**
+ * Configuration options for the updater.
+ *
+ * @property {string} [channel] - Update channel (e.g., "stable", "beta")
+ * @property {IntegrityPolicy} [integrityPolicy] - Policy for integrity verification
+ * @property {Function} [integrityChecker] - Custom integrity verification function
+ * @property {SignatureVerifierOptions | Function} [signatureVerifier] - Signature verification config or custom function
+ *
+ * @example
+ * ```typescript
+ * const updater = new Updater(source, remote, {
+ *   channel: "stable",
+ *   integrityPolicy: IntegrityPolicy.Strict,
+ *   signatureVerifier: {
+ *     algorithm: SignatureAlgorithm.Ed25519,
+ *     key: {
+ *       format: VerifyingKeyFormat.SpkiPem,
+ *       data: publicKeyPem
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom verification functions
+ * const updater = new Updater(source, remote, {
+ *   integrityChecker: async (data, integrity) => {
+ *     // Custom integrity verification
+ *     return true;
+ *   },
+ *   signatureVerifier: async (data, signature) => {
+ *     // Custom signature verification
+ *     return true;
+ *   }
+ * });
+ * ```
+ */
+export interface UpdaterOptions {
+  channel?: string
+  integrityPolicy?: IntegrityPolicy
+  integrityChecker?: (data: Uint8Array, integrity: string) => Promise<boolean>
+  signatureVerifier?: SignatureVerifierOptions | ((data: Uint8Array, signature: string) => Promise<boolean>)
+}
+/**
+ * Format of the public key used for signature verification.
+ *
+ * Different algorithms support different key formats.
+ *
+ * @example
+ * ```typescript
+ * import { VerifyingKeyFormat } from "@wvb/node";
+ * import fs from "fs";
+ *
+ * // PEM format (text)
+ * const pemKey = fs.readFileSync("./public-key.pem", "utf8");
+ * const config1 = {
+ *   format: VerifyingKeyFormat.SpkiPem,
+ *   data: pemKey
+ * };
+ *
+ * // DER format (binary)
+ * const derKey = fs.readFileSync("./public-key.der");
+ * const config2 = {
+ *   format: VerifyingKeyFormat.SpkiDer,
+ *   data: derKey
+ * };
+ *
+ * // Raw bytes (Ed25519 only)
+ * const rawKey = new Uint8Array(32);
+ * const config3 = {
+ *   format: VerifyingKeyFormat.Raw,
+ *   data: rawKey
+ * };
+ * ```
+ */
+export type VerifyingKeyFormat = /** SubjectPublicKeyInfo DER format (binary) */
+'spkiDer'|
+/** SubjectPublicKeyInfo PEM format (text) */
+'spkiPem'|
+/** PKCS#1 DER format (RSA only| binary) */
+'pkcs1Der'|
+/** PKCS#1 PEM format (RSA only| text) */
+'pkcs1Pem'|
+/** SEC1 format (ECDSA only| binary) */
+'sec1'|
+/** Raw key bytes (Ed25519 only| 32 bytes) */
+'raw';
+export type Version =  'v1';
+/**
+ * Writes a bundle to a file asynchronously.
+ *
+ * @param {Bundle} bundle - Bundle to write
+ * @param {string} filepath - Destination file path
+ * @returns {Promise<number>} Number of bytes written
+ * @throws {Error} If the file cannot be written
+ *
+ * @example
+ * ```typescript
+ * const builder = new BundleBuilder();
+ * builder.insertEntry("/index.html", Buffer.from("<html></html>"));
+ * const bundle = builder.build();
+ * await writeBundle(bundle, "output.wvb");
+ * ```
+ */
+export declare function writeBundle(bundle: Bundle, filepath: string): Promise<bigint>
+/**
+ * Writes a bundle to a buffer synchronously.
+ *
+ * @param {Bundle} bundle - Bundle to write
+ * @returns {Buffer} Bundle data as a buffer
+ *
+ * @example
+ * ```typescript
+ * const bundle = builder.build();
+ * const buffer = writeBundleIntoBuffer(bundle);
+ * console.log(`Bundle size: ${buffer.length} bytes`);
+ * ```
+ */
+export declare function writeBundleIntoBuffer(bundle: Bundle): Buffer