import { type WorkerLike } from './protocol.js'; import { type PolicyInput, type RuleInfo, type ScanInput, type ScannerErrorCode, type Verdict } from './types.js'; /** Default per-request timeout (ms). */ export declare const DEFAULT_TIMEOUT_MS = 30000; export interface ScannerOptions { /** * Per request (scan, listRules, worker start-up) in ms; default 30 000. * `Infinity` disables it. On timeout the worker is killed and the scan * gives an `ERROR` verdict (`LIMIT.TIMEOUT`). */ timeoutMs?: number; /** * Where the worker loads the engine from: a URL (resolved against the * page) or a compiled `WebAssembly.Module`. Default: the `.wasm` file * shipped next to the worker, located by your bundler. */ wasm?: string | URL | WebAssembly.Module; /** * Advanced: creates the worker (e.g. under a strict CSP or when the package * is served from another origin). It must run this package's `worker.js`. */ worker?: () => WorkerLike; } export interface ScanOptions { /** Overrides the scanner's `timeoutMs` for this scan. */ timeoutMs?: number; /** Aborting gives an `ERROR` verdict (`ENGINE.ABORTED`). */ signal?: AbortSignal; /** * `true`: hand the caller's `ArrayBuffer` (or the buffer of a `Uint8Array` * that spans it whole) to the worker without copying. The caller's buffer * is detached (length 0) afterwards. Default `false`: the bytes are copied * when `scan` is called and the caller's buffer is untouched. */ transfer?: boolean; } export interface ListRulesOptions { timeoutMs?: number; signal?: AbortSignal; } export interface Scanner { /** Engine version (`engine_version` in verdicts). */ readonly engineVersion: string; /** * Scans one file. Never rejects: anything that goes wrong (bad input, * timeout, abort, worker crash, `terminate()`) gives a verdict with * `status: "ERROR"` and `valid: false`. */ scan(input: ScanInput, policy?: PolicyInput, options?: ScanOptions): Promise; /** Every rule the engine knows, sorted by ID. Rejects with a {@link QueldaError}. */ listRules(options?: ListRulesOptions): Promise; /** Kills the worker. Pending scans give `ERROR` verdicts; later calls fail. Idempotent. */ terminate(): void; } /** Rejection reason of `createScanner` and `listRules`. */ export declare class QueldaError extends Error { readonly code: ScannerErrorCode; constructor(code: ScannerErrorCode, message: string); } /** A failure outside the engine (internal; never confused with DOMException & co). */ declare class Failure { readonly code: ScannerErrorCode; readonly message: string; constructor(code: ScannerErrorCode, message: string); } /** * A worker whose WASM memory grew past this after a scan is replaced * (memory is returned to the system). Scans of a `File` / `Blob` stay far * below; a large `ArrayBuffer` is copied into WASM memory whole. */ export declare const RECYCLE_MEMORY_BYTES: number; /** Validated timeout: `null` = none. Throws a Failure. */ export declare function resolveTimeout(value: unknown, fallback: number | null): number | null; /** * Turns the input into an `ArrayBuffer` the scanner owns (safe to transfer) * — copied unless `transfer` is set and the buffer can be handed over whole — * or a `Blob` / `File` as is: the worker reads only the parts the engine * needs (plan Step 16 Phase B). Throws / rejects with a Failure. */ export declare function normalizeInput(input: unknown, transfer: boolean): Promise; /** Policy JSON for the engine (which validates it). Throws a Failure. */ export declare function policyJson(policy: unknown): string; /** * Parses the engine's verdict JSON and checks its invariants (schema §7). * Fills `stats.duration_ms` (the WASM engine has no clock) with the * worker-measured engine time. Throws a Failure on anything unexpected. */ export declare function parseVerdict(text: unknown, durationMs: unknown): Verdict; /** Parses the engine's rule list; throws a Failure if it is not one. */ export declare function parseRules(text: unknown): RuleInfo[]; /** An `ERROR` verdict for failures outside the engine. */ export declare function errorVerdict(f: Failure, engineVersion: string, bytes: number, durationMs: number): Verdict; /** * Creates a scanner with an explicit worker factory and waits until its * engine is loaded. Rejects with a {@link QueldaError}. */ export declare function createScannerWith(makeWorker: () => WorkerLike, options?: ScannerOptions): Promise; export {};