portapack 0.2.1

package/dist/index.d.ts

@@ -0,0 +1,275 @@
+/**
+ * @file types.ts
+ *
+ * @description
+ * Centralized types used across the PortaPack CLI, API, core modules, and bundling pipeline.
+ *
+ * This file defines:
+ * - Asset structure
+ * - HTML parsing result
+ * - Bundling options and metadata
+ * - Page structures for recursive bundling
+ * - CLI execution output format
+ */
+/**
+ * Represents a single discovered, downloaded, or embedded asset.
+ * This includes JS, CSS, images, fonts, etc.
+ */
+interface Asset {
+    type: 'css' | 'js' | 'image' | 'font' | 'video' | 'audio' | 'other';
+    /** The resolved or original URL of the asset */
+    url: string;
+    /** Inlined or fetched content */
+    content?: string;
+    /** Font-specific metadata for font-face usage */
+    fontMeta?: {
+        familyName: string;
+        weight?: number;
+        style?: 'normal' | 'italic' | 'oblique';
+        format?: string;
+    };
+}
+/**
+ * Represents raw HTML and any linked/discovered assets.
+ * Result of the parsing stage.
+ */
+interface ParsedHTML {
+    htmlContent: string;
+    assets: Asset[];
+}
+/**
+ * Represents a single page crawled during recursive bundling.
+ * Used as input for the multi-page bundler.
+ */
+interface PageEntry {
+    /** Full resolved URL of the crawled page */
+    url: string;
+    /** Raw HTML content of the crawled page */
+    html: string;
+}
+/**
+ * Configuration options provided by the user via CLI or API call.
+ * Controls various aspects of the bundling process.
+ */
+interface BundleOptions {
+    /** Embed all discovered assets as data URIs (default: true) */
+    embedAssets?: boolean;
+    /** Enable HTML minification using html-minifier-terser (default: true) */
+    minifyHtml?: boolean;
+    /** Enable CSS minification using clean-css (default: true) */
+    minifyCss?: boolean;
+    /** Enable JavaScript minification using terser (default: true) */
+    minifyJs?: boolean;
+    /** Base URL for resolving relative links, especially for remote fetches or complex local structures */
+    baseUrl?: string;
+    /** Enable verbose logging during CLI execution */
+    verbose?: boolean;
+    /** Skip writing output file to disk (CLI dry-run mode) */
+    dryRun?: boolean;
+    /** Enable recursive crawling. If a number, specifies max depth. If true, uses default depth. */
+    recursive?: number | boolean;
+    /** Optional output file path override (CLI uses this) */
+    output?: string;
+    /** Log level for the internal logger */
+    logLevel?: LogLevel;
+}
+declare enum LogLevel {
+    NONE = 0,// No logging (equivalent to 'silent')
+    ERROR = 1,// Only errors
+    WARN = 2,// Errors and warnings
+    INFO = 3,// Errors, warnings, and info (Default)
+    DEBUG = 4
+}
+type LogLevelName = 'debug' | 'info' | 'warn' | 'error' | 'silent' | 'none';
+/**
+ * Summary statistics and metadata returned after the packing/bundling process completes.
+ */
+interface BundleMetadata {
+    /** Source HTML file path or URL */
+    input: string;
+    /** Total number of unique assets discovered (CSS, JS, images, fonts etc.) */
+    assetCount: number;
+    /** Final output HTML size in bytes */
+    outputSize: number;
+    /** Elapsed build time in milliseconds */
+    buildTimeMs: number;
+    /** If recursive bundling was performed, the number of pages successfully crawled and included */
+    pagesBundled?: number;
+    /** Any non-critical errors or warnings encountered during bundling (e.g., asset fetch failure) */
+    errors?: string[];
+}
+/**
+ * Standard result object returned from the main public API functions.
+ */
+interface BuildResult {
+    /** The final generated HTML string */
+    html: string;
+    /** Metadata summarizing the build process */
+    metadata: BundleMetadata;
+}
+/** CLI-specific options extending BundleOptions. */
+interface CLIOptions extends BundleOptions {
+    /** Input file or URL (positional). */
+    input?: string;
+    /** Max depth for recursive crawling (numeric alias for recursive). */
+    maxDepth?: number;
+    minify?: boolean;
+}
+/**
+ * Result object specifically for the CLI runner, capturing output streams and exit code.
+ */
+interface CLIResult {
+    /** Captured content written to stdout */
+    stdout?: string;
+    /** Captured content written to stderr */
+    stderr?: string;
+    /** Final exit code intended for the process (0 for success, non-zero for errors) */
+    exitCode: number;
+}
+
+/**
+ * @file src/utils/logger.ts
+ * @description Provides a standardized logging utility with configurable levels (based on an enum)
+ * to control output verbosity throughout the application (core, API, CLI).
+ */
+
+/**
+ * A simple logger class that allows filtering messages based on severity levels.
+ * Uses standard console methods (debug, info, warn, error) for output.
+ */
+declare class Logger {
+    /** The current minimum log level required for a message to be output. */
+    level: LogLevel;
+    /**
+     * Creates a new Logger instance.
+     * Defaults to LogLevel.INFO if no level is provided.
+     *
+     * @param {LogLevel} [level=LogLevel.INFO] - The initial log level for this logger instance.
+     * Must be one of the values from the LogLevel enum.
+     */
+    constructor(level?: LogLevel);
+    /**
+     * Updates the logger's current level. Messages below this level will be suppressed.
+     *
+     * @param {LogLevel} level - The new log level to set. Must be a LogLevel enum member.
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Logs a debug message if the current log level is DEBUG or higher.
+     *
+     * @param {string} message - The debug message string.
+     */
+    debug(message: string): void;
+    /**
+     * Logs an informational message if the current log level is INFO or higher.
+     *
+     * @param {string} message - The informational message string.
+     */
+    info(message: string): void;
+    /**
+     * Logs a warning message if the current log level is WARN or higher.
+     *
+     * @param {string} message - The warning message string.
+     */
+    warn(message: string): void;
+    /**
+     * Logs an error message if the current log level is ERROR or higher.
+     *
+     * @param {string} message - The error message string.
+     */
+    error(message: string): void;
+    /**
+     * Static factory method to create a Logger instance based on a simple boolean `verbose` flag.
+     *
+     * @static
+     * @param {{ verbose?: boolean }} [options={}] - An object potentially containing a `verbose` flag.
+     * @returns {Logger} A new Logger instance set to LogLevel.DEBUG if options.verbose is true,
+     * otherwise set to LogLevel.INFO.
+     */
+    static fromVerboseFlag(options?: {
+        verbose?: boolean;
+    }): Logger;
+    /**
+     * Static factory method to create a Logger instance based on a LogLevel string name.
+     * Useful for creating a logger from config files or environments variables.
+     *
+     * @static
+     * @param {string | undefined} levelName - The name of the log level (e.g., 'debug', 'info', 'warn', 'error', 'silent'/'none'). Case-insensitive.
+     * @param {LogLevel} [defaultLevel=LogLevel.INFO] - The level to use if levelName is invalid or undefined.
+     * @returns {Logger} A new Logger instance set to the corresponding LogLevel.
+     */
+    static fromLevelName(levelName?: string, defaultLevel?: LogLevel): Logger;
+}
+
+/**
+ * @file src/index.ts
+ * @description
+ * Main public API for the PortaPack library.
+ * Provides functions to create portable HTML files from local paths or URLs,
+ * including single-page fetching, recursive site crawling, and multi-page bundling.
+ * It coordinates calls to various core modules (parser, extractor, minifier, packer, web-fetcher, bundler).
+ */
+
+/**
+ * Generates a single, portable HTML file from a local file path or a remote URL.
+ *
+ * - **For local files:** Reads the file, parses it, discovers linked assets (CSS, JS, images, fonts),
+ * fetches/reads asset content, optionally embeds assets as data URIs (default),
+ * optionally minifies HTML/CSS/JS (default), and packs everything into a single HTML string.
+ * - **For remote URLs:** Fetches the HTML content of the single specified URL using the core web-fetcher.
+ * *Note: This does not process/embed assets for single remote URLs; it returns the fetched HTML as-is.*
+ *
+ * @export
+ * @param {string} input - The local file path or remote http(s) URL of the HTML document.
+ * @param {BundleOptions} [options={}] - Configuration options controlling embedding, minification,
+ * base URL, logging level, etc. See `BundleOptions` type for details.
+ * @param {Logger} [loggerInstance] - Optional pre-configured logger instance to use.
+ * @returns {Promise<BuildResult>} A promise resolving to an object containing the final HTML string
+ * and metadata (`BundleMetadata`) about the bundling process (input, size, time, assets, errors).
+ * @throws {Error} Throws errors if file reading, parsing, required asset fetching, or processing fails critically.
+ */
+declare function generatePortableHTML(input: string, options?: BundleOptions, loggerInstance?: Logger): Promise<BuildResult>;
+/**
+ * Crawls a website starting from a given URL up to a specified depth,
+ * bundles all discovered internal HTML pages into a single multi-page file,
+ * and returns the result.
+ *
+ * @export
+ * @param {string} url - The entry point URL to start crawling. Must be http or https.
+ * @param {number} [depth=1] - The maximum link depth to crawl (1 means only the starting page).
+ * @param {BundleOptions} [options={}] - Configuration options. Primarily used for `logLevel`.
+ * @param {Logger} [loggerInstance] - Optional pre-configured logger instance to use.
+ * @returns {Promise<BuildResult>} A promise resolving to an object containing the bundled multi-page HTML string
+ * and metadata (`BundleMetadata`) about the crawl and bundling process.
+ * @throws {Error} Throws errors if the initial URL is invalid, crawling fails, or bundling fails.
+ */
+declare function generateRecursivePortableHTML(url: string, depth?: number, options?: BundleOptions, loggerInstance?: Logger): Promise<BuildResult>;
+/**
+ * Fetches the HTML content of a single remote URL using the core web-fetcher.
+ * This function acts as a public wrapper, primarily adding standardized timing and metadata.
+ * It does *not* process assets within the fetched HTML.
+ *
+ * @export
+ * @param {string} url - The remote http(s) URL to fetch.
+ * @param {BundleOptions} [options={}] - Configuration options, mainly for `logLevel`.
+ * @param {Logger} [loggerInstance] - Optional pre-configured logger instance to use.
+ * @returns {Promise<BuildResult>} A promise resolving to the BuildResult containing the fetched HTML
+ * and metadata from the fetch operation.
+ * @throws {Error} Propagates errors directly from the core fetching function or if URL is invalid.
+ */
+declare function fetchAndPackWebPage(url: string, options?: BundleOptions, loggerInstance?: Logger): Promise<BuildResult>;
+/**
+ * Bundles an array of pre-fetched/generated HTML pages into a single static HTML file
+ * using `<template>` tags and a simple client-side hash-based router.
+ * This function does not perform any asset processing on the input HTML strings.
+ *
+ * @export
+ * @param {PageEntry[]} pages - An array of page objects, where each object has a `url` (for slug generation)
+ * and `html` (the content for that page).
+ * @param {BundleOptions} [options={}] - Configuration options, primarily used for `logLevel`.
+ * @param {Logger} [loggerInstance] - Optional pre-configured logger instance.
+ * @returns {string} A single HTML string representing the bundled multi-page document.
+ */
+declare function bundleMultiPageHTML(pages: PageEntry[], options?: BundleOptions, loggerInstance?: Logger): string;
+
+export { type Asset, type BuildResult, type BundleMetadata, type BundleOptions, type CLIOptions, type CLIResult, LogLevel, type LogLevelName, type PageEntry, type ParsedHTML, bundleMultiPageHTML, fetchAndPackWebPage, generatePortableHTML, generateRecursivePortableHTML };