@mrgoonie/multix 1.0.8 → 1.0.9

package/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.9](https://github.com/mrgoonie/multix-cli/compare/v1.0.8...v1.0.9) (2026-10-11)
+
+
+### Fixed
+
+* **build:** ship the programmatic entry point declared in package.json ([#132](https://github.com/mrgoonie/multix-cli/issues/132)) ([1c41397](https://github.com/mrgoonie/multix-cli/commit/1c41397c0b8fda141311fef0fbc5c278b660a67f))
+
 ## [1.0.8](https://github.com/mrgoonie/multix-cli/compare/v1.0.7...v1.0.8) (2026-10-11)
 
 

package/dist/index.d.ts

@@ -0,0 +1,339 @@
+/**
+ * Secret redaction helpers. Runtime-neutral (no node:* imports) so they can be
+ * shared by the CLI and non-Node runtimes such as a Cloudflare Worker.
+ */
+/**
+ * Redact an API key for safe logging: show first 6 + last 4 chars.
+ * e.g. "AIzaSy...abcd"
+ */
+declare function redact(key: string): string;
+/**
+ * Strip the query string and fragment from a URL so API keys passed as query
+ * parameters and pre-signed media tokens never reach logs or error messages.
+ * Opaque URLs (data:, blob:, file:) collapse to their scheme. Secrets embedded
+ * in the path itself are not detected. Non-URL input is returned unchanged
+ * except for anything after "?" or "#".
+ */
+declare function redactUrl(url: string): string;
+
+interface LoadEnvOptions {
+    /**
+     * Names a project env file (cwd/.env, or a legacy `.claude` file under cwd)
+     * may set: the variables multix reads (see src/project-env-names.ts). Shell
+     * variables and user-level files are not filtered.
+     */
+    isProjectEnvName: (name: string) => boolean;
+}
+/**
+ * Resolve a single environment variable by name.
+ * Returns undefined if not set (after env loading).
+ */
+declare function resolveKey(name: string): string | undefined;
+
+/**
+ * Custom error hierarchy for multix CLI.
+ * All errors carry a short `code` string for programmatic handling.
+ */
+declare class MultixError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string, options?: ErrorOptions);
+}
+/** Missing or invalid configuration (env vars, flags). */
+declare class ConfigError extends MultixError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Provider API returned an error or unexpected response. */
+declare class ProviderError extends MultixError {
+    readonly provider: string;
+    constructor(message: string, provider: string, options?: ErrorOptions);
+}
+/** Input validation failed (zod parse, file not found, etc.). */
+declare class ValidationError extends MultixError {
+    constructor(message: string);
+}
+/**
+ * HTTP request failed. The message and `url` show the request URL with its
+ * query string redacted so API keys and signed-URL tokens never reach
+ * terminal, CI or Worker logs; `rawUrl` keeps the original (non-enumerable).
+ */
+declare class HttpError extends MultixError {
+    readonly status: number;
+    readonly snippet: string;
+    /** Parsed Retry-After header (ms), when the server sent one. */
+    readonly retryAfterMs?: number | undefined;
+    /** Request URL with query string and fragment redacted — safe to log or serialize. */
+    readonly url: string;
+    /** Raw request URL. Non-enumerable so JSON.stringify/console output never includes it. */
+    readonly rawUrl: string;
+    constructor(status: number, snippet: string, url: string, 
+    /** Parsed Retry-After header (ms), when the server sent one. */
+    retryAfterMs?: number | undefined, options?: ErrorOptions);
+}
+
+/**
+ * Discriminated union Result type for all provider operations.
+ * Avoids throwing across async boundaries for expected failures.
+ */
+type OkResult<T> = {
+    status: "success";
+} & T;
+type ErrResult = {
+    status: "error";
+    error: string;
+};
+type Result<T> = OkResult<T> | ErrResult;
+/** Wrap a success payload into a Result. */
+declare function ok<T extends Record<string, unknown>>(data: T): OkResult<T>;
+/** Wrap an error message into a Result. */
+declare function err(message: string): ErrResult;
+/** Type guard: check if Result is success. */
+declare function isOk<T>(result: Result<T>): result is OkResult<T>;
+/** Type guard: check if Result is error. */
+declare function isErr<T>(result: Result<T>): result is ErrResult;
+
+/**
+ * Output directory management for generated files.
+ * Default: ./multix-output/ (override via MULTIX_OUTPUT_DIR env var).
+ * Created lazily on first call; memoized thereafter.
+ */
+/**
+ * Returns the absolute path to the output directory, creating it if needed.
+ * Respects MULTIX_OUTPUT_DIR environment variable.
+ */
+declare function getOutputDir(): string;
+
+/**
+ * Parse a CLI `--input` argument as inline JSON or `@path/to/file.json`.
+ * Shared by provider "run" commands that forward model-specific payloads.
+ */
+declare function parseJsonInput(raw: string, flag?: string): Record<string, unknown>;
+
+/**
+ * Redirect handling for requests that carry credentials (API key headers).
+ * Runtime-neutral: no node:* imports, so provider HTTP clients that also run
+ * outside Node (e.g. a Cloudflare Worker) can share it.
+ *
+ * fetch() follows redirects by itself and, per the Fetch spec, strips only
+ * `Authorization` on a cross-origin hop: custom key headers such as
+ * `X-Api-Key` or `x-goog-api-key` would be forwarded to the new origin. The
+ * helpers here follow redirects one hop at a time instead, so request headers
+ * never reach another origin (an https to http hop is an origin change too).
+ */
+
+/** Minimal fetch signature (matches globalThis.fetch for string URLs). */
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+
+/**
+ * Runtime-neutral JSON-over-HTTP helper (no node:* imports).
+ * Provider clients that must also run outside Node (e.g. a Cloudflare Worker)
+ * use this with an injected `fetch`; the CLI's `httpJson` delegates here.
+ */
+
+interface FetchJsonOptions {
+    url: string;
+    method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+    headers?: Record<string, string>;
+    body?: Record<string, unknown> | unknown[] | any;
+    timeoutMs?: number;
+    /** Defaults to globalThis.fetch, resolved at call time so tests can stub it. */
+    fetch?: FetchLike;
+}
+/**
+ * Parse a Retry-After header (delta-seconds or HTTP-date) into milliseconds.
+ * Returns undefined when absent or unparseable.
+ */
+declare function parseRetryAfter(value: string | null | undefined, now?: number): number | undefined;
+/** Build an HttpError from a non-2xx response, reading a bounded body snippet. */
+declare function httpErrorFromResponse(response: Response, url: string): Promise<HttpError>;
+/**
+ * Make an HTTP request and parse the JSON response.
+ * Throws HttpError on non-2xx status or network failure (status 0); a
+ * deterministic fetch rejection (invalid header or URL) becomes a
+ * non-retryable ConfigError or ProviderError (see `toFetchError`). When the
+ * request carries a header that may be a credential (anything but Accept,
+ * Accept-Language, Content-Type, User-Agent), redirects are followed within
+ * the same origin only; one to another origin is refused (HttpError with the
+ * 3xx status) so the key is never sent there. Requests without such headers
+ * follow redirects to any origin.
+ */
+declare function fetchJson<T>(opts: FetchJsonOptions): Promise<T>;
+
+/**
+ * HTTP utilities for multix CLI providers.
+ * Uses Node 20+ globalThis.fetch so tests can mock it via globalThis.fetch assignment.
+ * downloadFile streams to disk without buffering the full body.
+ */
+
+/**
+ * Make an HTTP request and parse the JSON response.
+ * Throws HttpError on non-2xx status.
+ */
+declare function httpJson<T>(opts: FetchJsonOptions): Promise<T>;
+/**
+ * Download a URL to a local file path, streaming to avoid large memory usage.
+ * Parent directory is created if it does not exist.
+ * Resolves with the response Content-Type (if any) so callers can name
+ * extensionless outputs. `headers` (e.g. an API key) are sent to the URL's
+ * own origin only: redirects are then followed by hand and the headers are
+ * dropped once a hop changes origin, including an https to http downgrade.
+ */
+declare function downloadFile(url: string, dest: string, timeoutMs?: number, headers?: Record<string, string>): Promise<string | undefined>;
+/**
+ * Decode a data: URI or download an http(s) URL, returning raw bytes.
+ */
+declare function fetchBytes(urlOrDataUri: string): Promise<Buffer>;
+
+/**
+ * Bounded polling for asynchronous provider jobs (predictions, video renders).
+ * Runtime-neutral (no node:* imports): exponential backoff with jitter, a hard
+ * deadline, transient-error retries, and Retry-After support on 429.
+ */
+
+declare class PollTimeoutError extends MultixError {
+    readonly lastStatus?: unknown | undefined;
+    constructor(message: string, lastStatus?: unknown | undefined);
+}
+interface PollOptions<T> {
+    /**
+     * Fetch the current job state. `remainingMs` is the time left before the
+     * deadline; use it as the request timeout so one slow request cannot
+     * overrun the overall wait.
+     */
+    fetchStatus: (ctx: {
+        remainingMs: number;
+        attempt: number;
+    }) => Promise<T>;
+    /** True once the job reached a terminal state (success OR failure). */
+    isTerminal: (state: T) => boolean;
+    /** Hard upper bound for the whole wait. */
+    timeoutMs: number;
+    /** First delay between polls. Default 3000ms. */
+    intervalMs?: number;
+    /** Ceiling for the backoff delay. Default 15000ms. */
+    maxIntervalMs?: number;
+    /** Multiplier applied after each poll. Default 1.5. */
+    backoffFactor?: number;
+    /** Add up to ±20% random jitter to each delay. Default true. */
+    jitter?: boolean;
+    /** Lower bound for any delay, including Retry-After: 0. Default 500ms. */
+    minIntervalMs?: number;
+    /** Errors that should be retried instead of aborting. Default: network/timeout, 408, 429, 5xx except 501/505. */
+    isTransientError?: (error: unknown) => boolean;
+    /** Called after each successful status fetch. */
+    onPoll?: (state: T, attempt: number) => void;
+    /** Appended to the timeout message, e.g. a resume command. */
+    resumeHint?: string;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    random?: () => number;
+}
+/**
+ * Network failures and timeouts (status 0), 408, rate limits and server errors
+ * are worth retrying. Anything else — ConfigError, ValidationError, other 4xx,
+ * 501 Not Implemented, 505 HTTP Version Not Supported, plain errors — fails the
+ * same way on every attempt.
+ */
+declare function isTransientHttpError(error: unknown): boolean;
+/**
+ * Poll `fetchStatus` until `isTerminal` returns true or the deadline passes.
+ * Returns the terminal state; callers decide whether it is success or failure.
+ * Throws PollTimeoutError on timeout and rethrows non-transient errors.
+ */
+declare function pollUntil<T>(opts: PollOptions<T>): Promise<T>;
+
+/**
+ * Simple ANSI-coloured logger for multix CLI.
+ * Uses no external deps — raw ANSI escape codes only.
+ * debug() is a no-op unless verbose mode is enabled.
+ */
+interface Logger {
+    info(msg: string): void;
+    success(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+    debug(msg: string): void;
+    /** Print a section header. */
+    header(msg: string): void;
+}
+declare function createLogger(opts: {
+    verbose: boolean;
+}): Logger;
+/** Convenience singleton used when verbose flag is not yet parsed. */
+declare const defaultLogger: Logger;
+
+/**
+ * Generic thumbnail/cover detection for provider video responses.
+ *
+ * Walks an arbitrary object looking for a small set of well-known field names
+ * (cover_image_url, thumbnail_url, etc.) whose value is an http(s) URL pointing
+ * to an image. Used by all video commands so a generated video's thumbnail is
+ * downloaded next to the .mp4 when the provider exposes one.
+ */
+
+/**
+ * Recursively walk `obj` for the first known thumbnail field whose value is a
+ * plausible image URL. Returns the URL string or null.
+ */
+declare function detectThumbUrl(obj: unknown): string | null;
+/**
+ * Downloads `url` to `dest`; lets a caller apply its own transport and naming
+ * policy. A result with a string `dest` names the file actually used (e.g. a
+ * free name beside `dest`, or a thumbnail that was already saved).
+ */
+type ThumbDownloader = (url: string, dest: string) => Promise<unknown>;
+/**
+ * Derive a `<base>_thumb.<ext>` path next to `videoPath` and download `thumbUrl`.
+ * Extension comes from the URL when recognizable, otherwise falls back to .jpg.
+ * Returns the saved path on success, null on failure (logged as warn).
+ */
+declare function downloadThumbBeside(thumbUrl: string, videoPath: string, logger?: Logger, download?: ThumbDownloader): Promise<string | null>;
+/**
+ * Convenience: detect and download in one call. Honors `skip` (e.g. --no-thumb).
+ * Also copies the thumb next to a user-supplied --output path when given.
+ */
+declare function maybeDownloadThumb(source: unknown, videoPath: string, opts?: {
+    skip?: boolean;
+    copyTo?: string;
+    logger?: Logger;
+    download?: ThumbDownloader;
+}): Promise<string | null>;
+
+/**
+ * Variable names a project-level `.env` may set: the names multix itself
+ * reads, minus the opt-ins a repository must not switch on for the user.
+ * Anything else in a project `.env` (NODE_OPTIONS, npm_config_*, LD_PRELOAD,
+ * proxy and TLS settings, …) is ignored by loadEnv, so a cloned repository
+ * cannot change how multix or the tools it spawns behave.
+ *
+ * Built from the constants the providers export where they exist; settings
+ * that are read inline are listed by hand below. Unit tests check the list
+ * against `.env.example` and against the names the source reads in the
+ * common forms (process.env reads, resolveKey calls, *_ENV constants, any
+ * `MULTIX_*` literal); a name read some other way must be added here by hand.
+ */
+/**
+ * Names multix reads that a project `.env` may NOT set: opt-ins that widen
+ * what a repository can do with the user's keys. MULTIX_LEGACY_CLAUDE_ENV
+ * would load credentials from the home folder's `.claude` files into a run
+ * the repository controls. Set these in the shell or ~/.multix/.env.
+ */
+declare const PROJECT_ENV_EXCLUDED: ReadonlySet<string>;
+/** Every fixed name a project `.env` may set (numbered Gemini keys are matched by pattern). */
+declare const PROJECT_ENV_NAMES: ReadonlySet<string>;
+/**
+ * True when a project `.env` may set `name`. On Windows env names are
+ * case-insensitive, so the check ignores case there, as the OS does.
+ */
+declare function isProjectEnvName(name: string, platform?: NodeJS.Platform): boolean;
+
+/**
+ * Programmatic API — re-exports public surface for library consumers.
+ */
+
+/**
+ * Load .env files once (see src/core/env-loader.ts). With no argument a
+ * project `.env` may only set the names multix reads (isProjectEnvName).
+ */
+declare function loadEnv(options?: LoadEnvOptions): void;
+
+export { ConfigError, type ErrResult, type FetchJsonOptions, type FetchLike, HttpError, type FetchJsonOptions as HttpJsonOptions, type LoadEnvOptions, type Logger, MultixError, type OkResult, PROJECT_ENV_EXCLUDED, PROJECT_ENV_NAMES, type PollOptions, PollTimeoutError, ProviderError, type Result, ValidationError, createLogger, defaultLogger, detectThumbUrl, downloadFile, downloadThumbBeside, err, fetchBytes, fetchJson, getOutputDir, httpErrorFromResponse, httpJson, isErr, isOk, isProjectEnvName, isTransientHttpError, loadEnv, maybeDownloadThumb, ok, parseJsonInput, parseRetryAfter, pollUntil, redact, redactUrl, resolveKey };