@opencraw/core 0.1.3 → 0.1.4

package/dist/transformation/apply-transform-chain.use-case.d.ts

@@ -0,0 +1,17 @@
+import type { TransformRule } from '../recipe-schema/index.js';
+import type { TransformContext } from './transform-registry.store.js';
+/**
+ * Applies a chain of transforms in order. A scalar op applied to a list runs
+ * on every item; a list op runs on the list itself. A missing value (`undefined`
+ * or `null`) passes through every op except `default`, `template` and `hook`,
+ * so a missing source reaches the missing-value policy untouched. Async because
+ * a `hook` may be.
+ *
+ * @param value - The resolved source value(s).
+ * @param rules - The chain.
+ * @param context - Lookup, hooks and the base URL.
+ * @returns The transformed value.
+ * @throws TransformError (or whatever a hook throws) when a step cannot apply.
+ */
+export declare function applyTransformChain(value: unknown, rules: readonly TransformRule[], context: TransformContext): Promise<unknown>;
+//# sourceMappingURL=apply-transform-chain.use-case.d.ts.map

package/dist/transformation/collection.algorithm.d.ts

@@ -0,0 +1,15 @@
+/** The input as a list: a list as is, a missing value as empty; anything else fails the op. */
+export declare function asList(op: string, value: unknown): unknown[];
+export declare function first(value: unknown): unknown;
+export declare function last(value: unknown): unknown;
+export declare function nth(value: unknown, index: number): unknown;
+export declare function slice(value: unknown, start: number, end?: number): unknown[];
+export declare function join(value: unknown, separator: string): string;
+export declare function concat(value: unknown, separator?: string): string;
+/** The first value that is not `undefined`, `null` or blank text. */
+export declare function coalesce(value: unknown): unknown;
+export declare function flatten(value: unknown): unknown[];
+export declare function unique(value: unknown): unknown[];
+export declare function sum(value: unknown): number;
+export declare function count(value: unknown): number;
+//# sourceMappingURL=collection.algorithm.d.ts.map

package/dist/transformation/currency.algorithm.d.ts

@@ -0,0 +1,15 @@
+/** A money amount with its ISO 4217 code, when known. */
+export interface Money {
+    amount: number;
+    currency?: string;
+}
+/**
+ * Parses a price. The currency comes from the explicit code, else a code or symbol in the text.
+ *
+ * @param value - Text such as `1.299,00 €` or a number.
+ * @param locale - The locale the text is written in.
+ * @param currency - An explicit ISO 4217 code that wins over anything in the text.
+ * @returns The money value.
+ */
+export declare function parseCurrency(value: unknown, locale?: string, currency?: string): Money;
+//# sourceMappingURL=currency.algorithm.d.ts.map

package/dist/transformation/date.algorithm.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Parses a date or instant.
+ *
+ * @param value - Text, a number (epoch milliseconds) or a Date.
+ * @param format - Tokens `YYYY MM DD HH mm ss`, e.g. `DD/MM/YYYY`; without one the text must be ISO 8601 or otherwise `Date.parse`-able.
+ * @param timezone - An IANA zone the text is written in when it carries no offset; default UTC.
+ * @returns The instant.
+ * @throws TransformError when the text cannot be read.
+ */
+export declare function parseDate(value: unknown, format?: string, timezone?: string): Date;
+/** `YYYY-MM-DD` of an instant, in UTC. */
+export declare function toIsoDate(date: Date): string;
+//# sourceMappingURL=date.algorithm.d.ts.map

package/dist/transformation/index.d.ts

@@ -0,0 +1,10 @@
+export { applyTransformChain } from './apply-transform-chain.use-case.js';
+export { BUILT_IN_TRANSFORMS } from './transform-registry.store.js';
+export type { TransformContext } from './transform-registry.store.js';
+export { TransformError } from './transform.error.js';
+export { parseNumber, parseInteger, parseBoolean } from './number.algorithm.js';
+export { parseCurrency } from './currency.algorithm.js';
+export type { Money } from './currency.algorithm.js';
+export { parseDate, toIsoDate } from './date.algorithm.js';
+export { absoluteUrl } from './url.algorithm.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/transformation/lookup.algorithm.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The first item of a table whose `key` path equals a value, compared as text
+ * so `"3"` finds `3`. The table is whatever a bound id holds: data, JSON text
+ * or a list of JSON texts (a `data-*` attribute per element).
+ *
+ * @param value - The value to find.
+ * @param table - The table, as bound in scope.
+ * @param key - A dotted path inside each item.
+ * @param pick - A dotted path to return from the item; the item itself when omitted.
+ * @returns The picked value, or `undefined` when nothing matches.
+ */
+export declare function lookup(value: unknown, table: unknown, key: string, pick?: string): unknown;
+/**
+ * Groups a list by a path, keeping first-seen order.
+ *
+ * @param items - The list.
+ * @param by - A dotted path inside each item; items without one group under `null`.
+ * @returns One `{ key, items }` per distinct key.
+ */
+export declare function group(items: unknown[], by: string): {
+    key: unknown;
+    items: unknown[];
+}[];
+//# sourceMappingURL=lookup.algorithm.d.ts.map

package/dist/transformation/number.algorithm.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The decimal and group separators a locale uses.
+ *
+ * @param locale - A BCP 47 tag; `undefined` means "guess from the text".
+ * @returns The two separators.
+ */
+export declare function separatorsOf(locale: string): {
+    decimal: string;
+    group: string;
+};
+/**
+ * Parses a number from text, tolerating currency symbols, spaces and locale separators.
+ *
+ * @param value - Text or a number.
+ * @param locale - The locale the text is written in. Without one, the last separator is the decimal one when
+ * it is followed by 1 or 2 digits, otherwise it is a group separator.
+ * @returns The number.
+ * @throws TransformError when no number can be read.
+ */
+export declare function parseNumber(value: unknown, locale?: string): number;
+export declare function parseInteger(value: unknown, locale?: string): number;
+/**
+ * Reads a boolean the way a recipe means it.
+ *
+ * @param value - Any value.
+ * @param truthy - Phrases that mean `true` (case-insensitive, matched as a substring); default: yes/true/1/on/in stock/available.
+ * @returns The boolean.
+ */
+export declare function parseBoolean(value: unknown, truthy?: readonly string[]): boolean;
+//# sourceMappingURL=number.algorithm.d.ts.map

package/dist/transformation/string.algorithm.d.ts

@@ -0,0 +1,18 @@
+/** A short description of a value for error messages. */
+export declare function describe(value: unknown): string;
+export declare function trim(value: unknown): string;
+export declare function lowercase(value: unknown): string;
+export declare function uppercase(value: unknown): string;
+export declare function replace(value: unknown, pattern: string, replacement: string, flags?: string): string;
+/**
+ * The first match of a pattern.
+ *
+ * @param value - The text.
+ * @param pattern - A regular expression source.
+ * @param group - The capture group to return; default: group 1 when the pattern has one, else the whole match.
+ * @param flags - Regular expression flags.
+ * @returns The captured text, or `undefined` when nothing matches.
+ */
+export declare function regex(value: unknown, pattern: string, group?: number, flags?: string): string | undefined;
+export declare function split(value: unknown, separator: string): string[];
+//# sourceMappingURL=string.algorithm.d.ts.map

package/dist/transformation/transform-registry.store.d.ts

@@ -0,0 +1,36 @@
+import type { HookRegistry } from '../hooks/index.js';
+import type { TransformOp, TransformRule } from '../recipe-schema/index.js';
+import type { Lookup } from '../template/index.js';
+/** What a transform may need besides its input. */
+export interface TransformContext {
+    recipeId: string;
+    /** Resolves template paths against the current scope. */
+    lookup: Lookup;
+    /** The scope snapshot, for hooks. */
+    scope: Record<string, unknown>;
+    hooks: HookRegistry;
+    /** The current page URL; `absoluteUrl` resolves against it by default. */
+    baseUrl?: string;
+    log: (level: 'debug' | 'info' | 'warn' | 'error', message: string, meta?: Record<string, unknown>) => void;
+}
+type RuleOf<Op extends TransformOp> = Extract<TransformRule, {
+    op: Op;
+}>;
+/** One registered operation. `elementwise` ops apply to each item when the input is a list. */
+interface Registered<Op extends TransformOp = TransformOp> {
+    elementwise: boolean;
+    apply: (value: unknown, rule: RuleOf<Op>, context: TransformContext) => unknown;
+}
+/** The closed set of built-in transforms, one per `TransformRule` op. */
+export declare const BUILT_IN_TRANSFORMS: {
+    [Op in TransformOp]: Registered<Op>;
+};
+/**
+ * Looks up the implementation of a rule.
+ *
+ * @param rule - A transform rule from a recipe.
+ * @returns The registered operation.
+ */
+export declare function transformFor(rule: TransformRule): Registered;
+export {};
+//# sourceMappingURL=transform-registry.store.d.ts.map

package/dist/transformation/transform.error.d.ts

@@ -0,0 +1,8 @@
+/** A transform that could not be applied to its input. */
+export declare class TransformError extends Error {
+    readonly op: string;
+    readonly input?: unknown;
+    readonly name = "TransformError";
+    constructor(op: string, reason: string, input?: unknown);
+}
+//# sourceMappingURL=transform.error.d.ts.map

package/dist/transformation/url.algorithm.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Percent-encodes a value for one URL component (a path segment, a query
+ * value), with `encodeURIComponent`'s rules: everything but letters, digits
+ * and `-_.!~*'()` is encoded, non-ASCII as UTF-8.
+ *
+ * @param value - Text, a number or a boolean.
+ * @returns The encoded text.
+ * @throws TransformError for anything else.
+ */
+export declare function urlEncode(value: unknown): string;
+/**
+ * Resolves a possibly relative URL.
+ *
+ * @param value - The URL text.
+ * @param base - What relative URLs resolve against; usually the page URL.
+ * @returns The absolute URL.
+ * @throws TransformError when the result is not a valid URL.
+ */
+export declare function absoluteUrl(value: unknown, base?: string): string;
+//# sourceMappingURL=url.algorithm.d.ts.map

package/dist/web-steps/evaluate-script.use-case.d.ts

@@ -0,0 +1,10 @@
+import type { Page } from 'playwright';
+import type { ExtractionScope } from '../extraction-scope/index.js';
+import type { EvaluateStep } from '../recipe-schema/index.js';
+/**
+ * Runs an `evaluate` step: the script is evaluated in the page as an expression
+ * (a function expression is called), and its JSON-serialisable result is bound
+ * under the step id. Trusted recipes only: this is arbitrary code in the page.
+ */
+export declare function evaluateScript(step: EvaluateStep, page: Page, scope: ExtractionScope): Promise<void>;
+//# sourceMappingURL=evaluate-script.use-case.d.ts.map

package/dist/web-steps/extract-from-page.use-case.d.ts

@@ -0,0 +1,10 @@
+import type { Page } from 'playwright';
+import type { ExtractionScope } from '../extraction-scope/index.js';
+import type { ExtractStep } from '../recipe-schema/index.js';
+/**
+ * Runs an `extract` step on the live page (css or xpath through locators, one
+ * round trip for all matches). With `from`, it reads a fragment bound earlier
+ * instead, the same way api mode reads a fetched document.
+ */
+export declare function extractFromPage(step: ExtractStep, page: Page, scope: ExtractionScope): Promise<void>;
+//# sourceMappingURL=extract-from-page.use-case.d.ts.map

package/dist/web-steps/index.d.ts

@@ -0,0 +1,2 @@
+export { WebStepRunner } from './run-web-step.use-case.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/web-steps/interact.use-case.d.ts

@@ -0,0 +1,36 @@
+import type { Locator, Page } from 'playwright';
+import type { ExtractionScope } from '../extraction-scope/index.js';
+import type { ClickStep, FillStep, PressStep, ScreenshotStep, ScrollStep, SelectStep, TargetFields, WaitStep } from '../recipe-schema/index.js';
+/**
+ * The element an interaction lands on: the first match of `selector`, or what
+ * `target` renders to - a live element (re-resolved by selector and index, so a
+ * re-render since the loop started does not matter) or a selector string.
+ *
+ * @param step - A step with `selector` or `target`.
+ * @param page - The page.
+ * @param scope - Where `target` is resolved.
+ * @returns The locator.
+ * @throws Error when `target` renders to something that is neither.
+ */
+export declare function targetOf(step: TargetFields, page: Page, scope: ExtractionScope): Locator;
+export declare function click(step: ClickStep, page: Page, scope: ExtractionScope): Promise<void>;
+export declare function fill(step: FillStep, page: Page, scope: ExtractionScope): Promise<void>;
+export declare function press(step: PressStep, page: Page, scope: ExtractionScope): Promise<void>;
+/** Picks an option of a `<select>` by value, label or index; each is a template. */
+export declare function select(step: SelectStep, page: Page, scope: ExtractionScope): Promise<void>;
+/**
+ * Scrolls to the bottom (or to an element) `times` times; with `untilStable`
+ * it keeps going until the page stops growing, which is how infinite lists end.
+ */
+export declare function scroll(step: ScrollStep, page: Page): Promise<void>;
+export declare function wait(step: WaitStep, page: Page): Promise<void>;
+/**
+ * Whether a locator becomes visible within a timeout. Never throws.
+ *
+ * @param target - The locator.
+ * @param timeout - Milliseconds to wait.
+ * @returns `true` when visible in time.
+ */
+export declare function appears(target: Locator, timeout: number): Promise<boolean>;
+export declare function screenshot(step: ScreenshotStep, page: Page, scope: ExtractionScope): Promise<void>;
+//# sourceMappingURL=interact.use-case.d.ts.map

package/dist/web-steps/navigate.use-case.d.ts

@@ -0,0 +1,15 @@
+import type { Page } from 'playwright';
+import type { EventBus } from '../crawl-events/index.js';
+import type { ExtractionScope } from '../extraction-scope/index.js';
+import type { GotoStep, InputRecipe } from '../recipe-schema/index.js';
+import type { RunGate } from '../step-flow/index.js';
+/**
+ * Runs a `goto` step: renders the URL (relative to the current page), waits for
+ * the gate's throttle (`delayMs`), navigates (again, after a pause, while it
+ * fails in passing: `limits.retry`), records the page's real URL in the scope,
+ * and checks the response against the recipe's block rule.
+ *
+ * @throws BlockedError when the response is a block.
+ */
+export declare function navigate(step: GotoStep, page: Page, scope: ExtractionScope, recipe: InputRecipe, gate: RunGate, events: EventBus): Promise<void>;
+//# sourceMappingURL=navigate.use-case.d.ts.map

package/dist/web-steps/run-web-step.use-case.d.ts

@@ -0,0 +1,37 @@
+import { BrowserSession } from '../browser-session/index.js';
+import type { CaptchaGuard } from '../captcha/index.js';
+import type { EventBus } from '../crawl-events/index.js';
+import type { ExtractionScope, LiveElement } from '../extraction-scope/index.js';
+import type { InputRecipe, PaginateNext, Step } from '../recipe-schema/index.js';
+import { RunGate } from '../step-flow/index.js';
+import type { NextPageResult, StepRunner } from '../step-flow/index.js';
+/**
+ * Runs web-mode leaf steps on a browser page. With a captcha guard, a page a
+ * navigation, click or key press leads to is checked for a challenge, solved
+ * before the next step runs.
+ */
+export declare class WebStepRunner implements StepRunner {
+    private readonly session;
+    private readonly recipe;
+    private readonly events;
+    private readonly gate;
+    private readonly captcha?;
+    private readonly page;
+    constructor(session: BrowserSession, recipe: InputRecipe, events: EventBus, gate?: RunGate, captcha?: CaptchaGuard | undefined);
+    /** Clicks and key presses can navigate; keep `page.url` honest after every leaf step. */
+    private trackUrl;
+    /** Navigates; a block page showing a captcha is solved under `onBlock.solve`, and a page reached is checked for one. */
+    private visit;
+    runLeaf(step: Step, scope: ExtractionScope): Promise<void>;
+    nextPage(next: PaginateNext, scope: ExtractionScope): Promise<NextPageResult>;
+    /**
+     * A runner on a new tab of the same context, for one parallel iteration:
+     * it shares cookies, the gate and the captcha guard; disposing it closes the tab only.
+     *
+     * @returns The forked runner.
+     */
+    fork(): Promise<WebStepRunner>;
+    elements(selector: string): Promise<LiveElement[]>;
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=run-web-step.use-case.d.ts.map

package/dist/web-steps/snapshot-elements.use-case.d.ts

@@ -0,0 +1,13 @@
+import type { Page } from 'playwright';
+import type { LiveElement } from '../extraction-scope/index.js';
+/**
+ * Snapshots every element a selector matches, in one round trip, for a
+ * `forEach` over `selector`. Each snapshot carries the selector and its index
+ * so a later `target` can find the element again, even after a re-render.
+ *
+ * @param selector - A css selector (or `xpath=...`), already rendered.
+ * @param page - The page.
+ * @returns One snapshot per match, in document order.
+ */
+export declare function snapshotElements(selector: string, page: Page): Promise<LiveElement[]>;
+//# sourceMappingURL=snapshot-elements.use-case.d.ts.map

package/dist/workbook-document/csv-parser.algorithm.d.ts

@@ -0,0 +1,26 @@
+/** The delimiters detection chooses between, in order of preference on a tie. */
+export declare const CSV_DELIMITERS: readonly [',', ';', '\t', '|'];
+/**
+ * Parses CSV text (RFC 4180, tolerant): a field in double quotes may hold the
+ * delimiter, line breaks and `""` for a quote; a quote inside an unquoted
+ * field is taken literally (`1.0 Hybrid "Cross"`); CRLF, LF and CR all end a
+ * record. Rows are kept as read: ragged rows stay ragged, nothing is trimmed.
+ *
+ * @param text - The decoded file.
+ * @param delimiter - One character.
+ * @returns The rows; a trailing empty line adds no row.
+ */
+export declare function parseCsv(text: string, delimiter: string): string[][];
+/**
+ * Chooses the delimiter of a CSV: the candidate whose field count (above one)
+ * is the most consistent over the first lines, so a title line or two above
+ * the header does not mislead it. A file of one column gets `,`.
+ *
+ * `;` with decimal commas (`Panda;15.950,00`), the usual European export,
+ * scores `;`: a comma split gives rows of uneven width.
+ *
+ * @param text - The decoded file.
+ * @returns The delimiter.
+ */
+export declare function detectDelimiter(text: string): string;
+//# sourceMappingURL=csv-parser.algorithm.d.ts.map

package/dist/workbook-document/csv-workbook.mapper.d.ts

@@ -0,0 +1,24 @@
+import type { WorkbookDocument } from './workbook-document.model.js';
+/**
+ * Reads decoded CSV text into a workbook of one sheet, named after the file.
+ *
+ * @param text - The decoded file.
+ * @param options - The sheet name, the encoding it was decoded from (for a
+ * probe to report) and a delimiter; without one it is detected.
+ * @returns The workbook.
+ * @throws Error when the delimiter given is not one character.
+ */
+export declare function csvWorkbook(text: string, options: {
+    name: string;
+    encoding: string;
+    delimiter?: string;
+}): WorkbookDocument;
+/**
+ * The name a CSV's sheet takes: the file name without its extension
+ * (`…/prezzo_alle_8.csv` → `prezzo_alle_8`), else `csv`.
+ *
+ * @param url - Where the file came from.
+ * @returns The name.
+ */
+export declare function sheetNameOf(url: string): string;
+//# sourceMappingURL=csv-workbook.mapper.d.ts.map

package/dist/workbook-document/grid-table.algorithm.d.ts

@@ -0,0 +1,53 @@
+import type { WorkbookCell, WorkbookDocument } from './workbook-document.model.js';
+/** What a table extract looks for in a workbook. */
+export interface GridTableQuery {
+    /** Matches a table's (first) header row: its non-empty cells joined by spaces, whitespace collapsed. */
+    header: RegExp;
+    /** Matches the row that ends a table; a table also ends at the next header or the sheet's end. `^$` ends it at the first empty row. */
+    until?: RegExp;
+    /** Output key -> a pattern for that column's header; unmatched columns are dropped. Without it, the headers are the keys. */
+    columns?: Record<string, RegExp>;
+    /** Matches the names of the sheets to read; default every sheet. */
+    sheet?: RegExp;
+    /** How many rows the header spans (default 1): a column's key joins its header texts. */
+    headerRows?: number;
+    /** Output keys whose empty cells take the value of the row above. */
+    fillDown?: string[];
+    /** Read hidden sheets and hidden rows too. */
+    includeHidden?: boolean;
+}
+/** One table found in a workbook. */
+export interface GridTable {
+    sheet: string;
+    /** The first header cell: the table's name when it has one. */
+    title: string;
+    /** The column keys, left to right. */
+    header: string[];
+    /** One object per row, keyed by column; text trimmed, numbers and booleans as they are. */
+    rows: Record<string, WorkbookCell>[];
+}
+/**
+ * Finds every table whose header row matches, in every sheet the query
+ * selects, and reads its rows by column. Unlike a PDF, a grid needs no
+ * geometry: column *i* of a row belongs to header *i*.
+ *
+ * Merged ranges are filled first (the file stores their value in the top-left
+ * cell only), so a brand merged down its models' rows reads on every row, and
+ * a group header merged across its sub-columns names each of them. Empty rows
+ * are skipped.
+ *
+ * @param document - The workbook.
+ * @param query - Which tables, and how to name their columns.
+ * @returns The tables, sheet by sheet, top to bottom.
+ */
+export declare function findGridTables(document: WorkbookDocument, query: GridTableQuery): GridTable[];
+/**
+ * Fills blank cells in the given columns with the value of the row above,
+ * within one table: pivot exports write a group's name on its first row only.
+ *
+ * @param rows - The table's rows, in order.
+ * @param keys - The columns to fill.
+ * @returns The rows, filled (new objects; the input is not changed).
+ */
+export declare function fillDown<Row extends Record<string, unknown>>(rows: readonly Row[], keys: readonly string[]): Row[];
+//# sourceMappingURL=grid-table.algorithm.d.ts.map

package/dist/workbook-document/html-tables.mapper.d.ts

@@ -0,0 +1,14 @@
+import type { Sheet } from './workbook-document.model.js';
+/**
+ * Every `<table>` of an HTML document as a sheet (`table 1`, `table 2`…, in
+ * document order), so the workbook table reader works on web pages and
+ * rendered Markdown: rows in order (`thead`, `tbody`, `tfoot` alike), `th` and
+ * `td` alike, cell text with whitespace collapsed, `colspan` and `rowspan` as
+ * merged ranges. A table inside a table is a sheet of its own, and its rows
+ * are not its parent's.
+ *
+ * @param html - The document.
+ * @returns The tables.
+ */
+export declare function htmlTableSheets(html: string): Sheet[];
+//# sourceMappingURL=html-tables.mapper.d.ts.map

package/dist/workbook-document/index.d.ts

@@ -0,0 +1,9 @@
+export { workbookText, isWorkbookDocument } from './workbook-document.model.js';
+export type { WorkbookDocument, Sheet, CsvFormat, WorkbookCell } from './workbook-document.model.js';
+export { parseCsv, detectDelimiter, CSV_DELIMITERS } from './csv-parser.algorithm.js';
+export { csvWorkbook, sheetNameOf } from './csv-workbook.mapper.js';
+export { readXlsxWorkbook } from './read-xlsx.client.js';
+export { findGridTables, fillDown } from './grid-table.algorithm.js';
+export { htmlTableSheets } from './html-tables.mapper.js';
+export type { GridTable, GridTableQuery } from './grid-table.algorithm.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/workbook-document/read-xlsx.client.d.ts

@@ -0,0 +1,18 @@
+import type { WorkbookDocument } from './workbook-document.model.js';
+/**
+ * Reads an `.xlsx` workbook into a workbook document, through
+ * `@opencraw/office-reader`: every worksheet's cells, with hidden sheets,
+ * hidden rows and merged ranges. Numbers and booleans keep their type (a
+ * cell's `13955.625` is unambiguous; as text, a locale guess could read it as
+ * thirteen million), dates become ISO text, errors their text, empty cells
+ * `''`. Formulas give their cached value. The reader is imported on first use,
+ * so recipes that never read a spreadsheet never load it.
+ *
+ * @param bytes - The file.
+ * @param source - Where it came from, for messages.
+ * @returns The workbook.
+ * @throws Error naming the source, and saying what to do, for a file that is
+ * not a readable workbook (a legacy `.xls`, a password-protected file, an `.ods`…).
+ */
+export declare function readXlsxWorkbook(bytes: Uint8Array, source: string): Promise<WorkbookDocument>;
+//# sourceMappingURL=read-xlsx.client.d.ts.map

package/dist/workbook-document/workbook-document.model.d.ts

@@ -0,0 +1,51 @@
+/**
+ * A cell: text, or, from a spreadsheet, the number or boolean it holds
+ * (`13955.625` stays a number, so no locale guess can misread it). Dates are
+ * ISO text (`2026-06-01`, `2026-06-01T09:30:00`), errors their text
+ * (`#DIV/0!`), an empty cell `''`. A CSV's cells are all text.
+ */
+export type WorkbookCell = string | number | boolean;
+/** One sheet of a workbook. A CSV is a workbook of one sheet. */
+export interface Sheet {
+    name: string;
+    /** Top to bottom; a row holds as many cells as were read (rows can be ragged). */
+    rows: WorkbookCell[][];
+    /** A sheet hidden in the workbook: `table` skips it unless `includeHidden`. */
+    hidden?: boolean;
+    /** Rows hidden in the sheet (0-based): `table` skips them unless `includeHidden`. */
+    hiddenRows?: number[];
+    /**
+     * Merged ranges as A1 references (`B10:B13`). The value of a merged range
+     * sits in its top-left cell only, as the file stores it; `table` copies it
+     * into every cell the range covers.
+     */
+    merges?: string[];
+}
+/** How a CSV was read, for a probe to report. */
+export interface CsvFormat {
+    encoding: string;
+    delimiter: string;
+}
+/** A spreadsheet or a CSV read into sheets of cells: what `extract` works on. */
+export interface WorkbookDocument {
+    kind: 'workbook';
+    sheets: Sheet[];
+    /** Present when the workbook came from a CSV. */
+    csv?: CsvFormat;
+}
+/**
+ * The text a `regex` extract reads: the visible rows of the visible sheets,
+ * cells separated by a tab, sheets separated by a blank line.
+ *
+ * @param document - The workbook.
+ * @returns The text.
+ */
+export declare function workbookText(document: WorkbookDocument): string;
+/**
+ * Whether a value bound in scope is a read workbook (so `extract … from` can take it).
+ *
+ * @param value - Anything.
+ * @returns Whether it is a {@link WorkbookDocument}.
+ */
+export declare function isWorkbookDocument(value: unknown): value is WorkbookDocument;
+//# sourceMappingURL=workbook-document.model.d.ts.map

package/dist/xml-document/index.d.ts

@@ -0,0 +1,6 @@
+export type { XmlDocument } from './xml-document.model.js';
+export { isXmlDocument } from './xml-document.model.js';
+export { parseXml, htmlAsXml, withoutNamespaces, serializeXml, gunzipIfNeeded } from './xml-parser.client.js';
+export { selectXpath, takeFromXml } from './xpath.algorithm.js';
+export type { XpathValue, XpathOptions } from './xpath.algorithm.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/xml-document/xml-document.model.d.ts

@@ -0,0 +1,13 @@
+/** A fetched XML document: a feed, a sitemap, an open-data export. Kept as text; queries parse it once. */
+export interface XmlDocument {
+    kind: 'xml';
+    xml: string;
+}
+/**
+ * Whether a value is a read XML document.
+ *
+ * @param value - Anything bound in a scope.
+ * @returns `true` for an `XmlDocument`.
+ */
+export declare function isXmlDocument(value: unknown): value is XmlDocument;
+//# sourceMappingURL=xml-document.model.d.ts.map

package/dist/xml-document/xml-parser.client.d.ts

@@ -0,0 +1,49 @@
+/** A parsed document, as the XPath engine sees it. */
+export type XmlNode = Node;
+/**
+ * Parses XML strictly but safely: a malformed document is an error naming
+ * the URL and the line; entities a DOCTYPE declares are never expanded (no
+ * "billion laughs") and nothing external is ever fetched (no XXE), they stay
+ * as they are.
+ *
+ * @param xml - The document text.
+ * @param where - The URL or id, for messages.
+ * @returns The document.
+ * @throws Error when the text is not well-formed XML.
+ */
+export declare function parseXml(xml: string, where: string): Document;
+/**
+ * HTML as an XML document, for XPath on fetched pages: parsed the way a
+ * browser parses it (a forgiving HTML5 parser that inserts `<tbody>` and
+ * closes what the page left open), without namespaces, so `//table/tbody/tr`
+ * finds what it finds on the live page.
+ *
+ * @param html - A page or a fragment.
+ * @returns The document.
+ */
+export declare function htmlAsXml(html: string): Document;
+/**
+ * A copy of a document with every namespace dropped: elements and attributes
+ * keep their local names, `xmlns` declarations go. What `ignoreNamespaces`
+ * queries run on: `//entry/title` instead of `//atom:entry/atom:title`.
+ *
+ * @param document - A parsed document.
+ * @returns The copy.
+ */
+export declare function withoutNamespaces(document: Document): Document;
+/**
+ * A node as markup: the element with its children (`outer`), or its children only.
+ *
+ * @param node - A node.
+ * @param outer - Whether to include the node itself.
+ * @returns The markup.
+ */
+export declare function serializeXml(node: Node, outer: boolean): string;
+/**
+ * The text of an XML body, gunzipped first when it is gzip (a `sitemap.xml.gz`).
+ *
+ * @param bytes - The body.
+ * @returns The bytes to decode.
+ */
+export declare function gunzipIfNeeded(bytes: Uint8Array): Uint8Array;
+//# sourceMappingURL=xml-parser.client.d.ts.map