hazo_scrape 1.0.1

package/CHANGE_LOG.md

@@ -0,0 +1,5 @@
+# hazo_scrape — Change Log
+
+## 1.0.0 — 2026-07-17
+
+- Initial release.

package/README.md

@@ -0,0 +1,145 @@
+# hazo_scrape
+
+Generic source-agnostic web scraping engine with a network-free parse core.
+
+`hazo_scrape/parse` maps HTML/IR table columns to logical fields by matching
+**header text**, not column position — so it survives a source reordering or
+adding columns. It has no network dependency (no fetch, no crawler) and no
+domain knowledge (no currency, no franking rules): you hand it HTML you
+already fetched plus a keyword map describing the fields you want, and it
+tells you which header(s) matched each field, flags anything ambiguous, and
+parses each matched cell's raw text into a number, an ISO date, or trimmed
+text. Because it's pure and network-free, it's fully unit-testable against
+static HTML fixtures.
+
+## Installation
+
+```bash
+npm install hazo_scrape
+```
+
+## Quick start
+
+```ts
+import { extractTable, mapColumns, mapRows, type ColumnKeywords } from 'hazo_scrape/parse';
+
+const html = `
+  <table>
+    <tr><th>Ex-Dividend Date</th><th>Amount</th><th>Franking</th></tr>
+    <tr><td>5 Mar 2026</td><td>$0.45</td><td>100%</td></tr>
+  </table>
+`;
+
+// 1. Pull the best-guess data table out of the page (or pass { select } to
+//    target a specific element).
+const table = extractTable(html); // { headers, rows, warning? }
+
+// 2. Declare the fields you care about and how to recognise their header.
+const keywords: ColumnKeywords = {
+  exDate: { keywords: ['ex-dividend', 'ex date'], type: 'date' },
+  amount: { keywords: ['amount', 'dividend'], type: 'number' },
+  franking: { keywords: ['franking'], type: 'text' },
+};
+
+// 3. Map headers -> candidate columns. dateGuard keeps a "date"-looking
+//    header (e.g. "Ex-Dividend Date") from also matching a non-date key
+//    (e.g. "amount", even though the header contains "dividend").
+const map = mapColumns(table.headers, keywords, { dateGuard: true, required: ['amount'] });
+
+if (!map.ok) {
+  throw new Error(`Missing required column(s): ${map.unmatched.join(', ')}`);
+}
+if (map.ambiguous.length > 0) {
+  console.warn('Ambiguous columns, caller must disambiguate:', map.ambiguous);
+}
+
+// 4. Join the map back onto the row data and parse each matched cell.
+const rows = mapRows(table, map, keywords);
+console.log(rows[0].amount[0].value); // 0.45
+console.log(rows[0].exDate[0].value); // "2026-03-05"
+```
+
+## API
+
+### `extractTable(html: string, opts?: { select?: string }): { headers: string[]; rows: string[][]; warning?: string }`
+
+Parses network-free HTML and returns the best-guess data table as raw header
+and row strings. Pass `opts.select` (a CSS selector) to target a specific
+`<table>` instead of letting the built-in scoring heuristic pick one. A
+`warning` is returned (never thrown) when no table-like element is found, or
+when `select` matches nothing.
+
+### `mapColumns(headers: string[], keywords: ColumnKeywords, opts?: { dateGuard?: boolean; required?: string[] }): ColumnMap`
+
+Matches each header against every key's `keywords` (case-insensitive
+substring match) and returns **all** matching headers per key — never just
+the first. `opts.dateGuard` drops date-looking headers from any key whose
+`type !== 'date'`. `opts.required` lists keys that must have at least one
+candidate for `map.ok` to be `true`.
+
+### `mapRows(table: { headers; rows }, map: ColumnMap, keywords: ColumnKeywords): MappedRow[]`
+
+Joins a `ColumnMap` back onto `table.rows`, producing one `MappedRow` per data
+row. Each matched key holds an array of `Cell`s (one per candidate header),
+each parsed according to that key's declared `type`.
+
+### `parseNumber(raw: string): number | null`
+
+Strips currency symbols, 3-letter currency codes, thousands-separator commas,
+and `%`, then parses what remains as a number. Returns `null` when nothing
+parseable is left. Does **not** convert cents to dollars — domain scaling is
+the caller's job.
+
+### `parseDate(raw: string, opts?: { formats?: string[] }): string | null`
+
+Parses a handful of common date text formats (ISO, `D Mon YYYY`, `Mon D,
+YYYY`, and `D/M/Y` slash dates) into an ISO `yyyy-mm-dd` string. Returns
+`null` — never a guess — for anything unrecognised or genuinely ambiguous
+(e.g. `05/03/2026` with no `opts.formats` hint and both components `<= 12`).
+
+### Types
+
+```ts
+type ColumnSpec = { keywords: string[]; type: 'number' | 'date' | 'text' };
+type ColumnKeywords = Record<string, ColumnSpec>;
+type Candidate = { header: string; index: number };
+type ColumnMap = {
+  ok: boolean;                          // false when any required key has zero candidates
+  matched: Record<string, Candidate[]>; // every match, in header order, one entry per key
+  unmatched: string[];                  // headers that matched no key at all
+  ambiguous: string[];                  // keys with 2+ candidates — reported, never resolved
+  headers: string[];
+};
+type Cell = { header: string; index: number; raw: string; value: number | string | null };
+type MappedRow = Record<string, Cell[]>;
+```
+
+## Design
+
+- **One-to-many, never resolved.** Every header matching a key is returned as
+  a candidate; if a table has both "Dividend (USD)" and "Dividend (AUD)",
+  both show up under `amount` and the key is reported in `ambiguous`. The
+  engine will not guess which one is "right" — the caller (e.g. an
+  `/aud/i` rule for a specific stock) makes that call.
+- **`dateGuard` is generic, not hardcoded.** Rather than special-casing
+  header text like "exDate", it uses each key's declared `type`: any header
+  that reads as a date is only eligible for keys typed `'date'`.
+- **Required, not scored.** `mapColumns` doesn't guess at "good enough" —
+  the caller declares which keys are `required`, and `ok` reflects exactly
+  that.
+- **Domain interpretation is the caller's job.** Cents-to-dollars scaling,
+  "Unfranked" -> `0`, currency selection, and similar business rules are
+  deliberately outside this engine. `parseNumber` and `parseDate` return the
+  literal parsed value (or `null`) and nothing else.
+
+## Tailwind v4 (`@source` required)
+
+If this package renders UI, add the following to your app's CSS entry:
+
+```css
+@source "../node_modules/hazo_scrape/dist";
+```
+
+## License
+
+MIT

package/SETUP_CHECKLIST.md

@@ -0,0 +1,17 @@
+# hazo_scrape — Setup Checklist
+
+Follow these steps when adding hazo_scrape to a consuming application.
+
+## 1. Install the package
+
+```bash
+npm install hazo_scrape
+```
+
+## 2. Configure
+
+<!-- TODO: list required env vars or config file entries -->
+
+## 3. Verify
+
+<!-- TODO: add a smoke-test or health-check step -->

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './lib/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+// hazo_scrape/src/index.ts — Server entry point
+// Import hazo_core via peer dep: import { HazoError } from 'hazo_core';
+export * from './lib/index.js';

package/dist/lib/index.d.ts

@@ -0,0 +1,2 @@
+export * from '../parse/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AACA,cAAc,mBAAmB,CAAC"}

package/dist/lib/index.js

@@ -0,0 +1,2 @@
+// hazo_scrape/src/lib/index.ts — Core library exports
+export * from '../parse/index.js';

package/dist/parse/extract_table.d.ts

@@ -0,0 +1,10 @@
+export type ExtractTableResult = {
+    headers: string[];
+    rows: string[][];
+    warning?: string;
+};
+export type ExtractTableOptions = {
+    select?: string;
+};
+export declare function extractTable(html: string, opts?: ExtractTableOptions): ExtractTableResult;
+//# sourceMappingURL=extract_table.d.ts.map

package/dist/parse/extract_table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract_table.d.ts","sourceRoot":"","sources":["../../src/parse/extract_table.ts"],"names":[],"mappings":"AAsBA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAwGF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,mBAAmB,GAAG,kBAAkB,CAyBzF"}

package/dist/parse/extract_table.js

@@ -0,0 +1,134 @@
+// hazo_scrape/src/parse/extract_table.ts — pure, network-free HTML table extraction
+//
+// Port of the TABLE-LOCATION spirit of the divscraper prototype's
+// findDividendTable/parseDividendTable (see dividends.mjs), but this engine is
+// generic: it has NO access to domain column keywords (no headerMap), so it
+// cannot score a table by "how many logical dividend columns did we match".
+// Column meaning is decided later, by a caller with a keyword map (see
+// map_columns.ts) — this module only decides which table looks like table
+// DATA and what its raw cells say.
+//
+// TYPING NOTE: this file deliberately never imports a node type (e.g.
+// `Element`) from the standalone `domhandler` package. The workspace root
+// hoists an older `domhandler` than the one cheerio bundles internally, and
+// naming that mismatched type here breaks structural assignability against
+// cheerio's own `Cheerio<Element>` values. Instead every helper takes a
+// `Cheerio<any>` selection and indexes with `.eq()` rather than unwrapping to
+// a raw node, so TypeScript never has to compare two differently-sourced
+// node types against each other.
+import { load } from 'cheerio';
+const NO_TABLE_WARNING = 'No table-like element found on the page (it may be JavaScript-rendered — a static HTML fetch will not see content injected by client-side JS).';
+// Collapse all whitespace (including &nbsp; -> U+00A0, decoded by cheerio's
+// .text()) into single spaces and trim. Real IR tables routinely pad cells
+// with &nbsp; and embedded newlines; left alone these corrupt comparisons and
+// downstream number/date parsing. JS's `\s` already matches U+00A0.
+function normalizeCell(raw) {
+    return raw.replace(/\s+/g, ' ').trim();
+}
+// Rows that belong directly to THIS table — not to any table nested inside a
+// cell. `tr` may be a direct child of <table>, or a child of a direct
+// <thead>/<tbody>/<tfoot> child. Collecting via `.children()` at each level
+// (rather than `.find('tr')`) prevents a nested table's rows leaking in.
+// `.add()` merges and re-sorts in document order, so the header (first row)
+// is always correct regardless of whether it lives in a <thead> or a bare
+// leading <tr>.
+function tableRows(tableSel) {
+    const direct = tableSel.children('tr');
+    const sectioned = tableSel.children('thead, tbody, tfoot').children('tr');
+    return direct.add(sectioned);
+}
+// Generic "table-ness" score — no domain keywords available here.
+//   +2 per header-ish cell (th/td) in the first row  — wider tables read more like data grids
+//   +5 flat bonus if the header row uses <th>          — semantic markup is a strong signal
+//   +3 per data row (rows after the header with >=1 <td>) — more rows = more likely the real data
+//   +10 * consistencyRatio, where consistencyRatio is the fraction of data
+//        rows whose cell count matches the header's cell count — a real data
+//        table has a stable column count; a layout/nav table used for markup
+//        rarely does.
+// A table with zero rows scores 0 and is never selected over one with rows.
+// Ties keep the first table encountered (strict `>` when updating best).
+function scoreTable(tableSel) {
+    const rows = tableRows(tableSel);
+    if (rows.length === 0)
+        return 0;
+    const headerCells = rows.eq(0).children('th, td');
+    const numHeaderCells = headerCells.length;
+    const hasTh = headerCells.filter('th').length > 0;
+    const dataRowsSel = rows.slice(1);
+    let numDataRows = 0;
+    let numConsistent = 0;
+    for (let i = 0; i < dataRowsSel.length; i++) {
+        const tdCount = dataRowsSel.eq(i).children('td').length;
+        if (tdCount === 0)
+            continue;
+        numDataRows += 1;
+        if (tdCount === numHeaderCells)
+            numConsistent += 1;
+    }
+    const consistencyRatio = numDataRows > 0 ? numConsistent / numDataRows : 0;
+    return numHeaderCells * 2 + (hasTh ? 5 : 0) + numDataRows * 3 + consistencyRatio * 10;
+}
+function readTable(tableSel) {
+    const rows = tableRows(tableSel);
+    if (rows.length === 0)
+        return { headers: [], rows: [] };
+    const headerCells = rows.eq(0).children('th, td');
+    const headers = [];
+    for (let i = 0; i < headerCells.length; i++) {
+        headers.push(normalizeCell(headerCells.eq(i).text()));
+    }
+    const dataRowsSel = rows.slice(1);
+    const dataRows = [];
+    for (let i = 0; i < dataRowsSel.length; i++) {
+        const tds = dataRowsSel.eq(i).children('td');
+        if (tds.length === 0)
+            continue; // skip non-data rows (prototype behaviour)
+        const cells = [];
+        for (let j = 0; j < tds.length; j++) {
+            cells.push(normalizeCell(tds.eq(j).text()));
+        }
+        dataRows.push(cells);
+    }
+    return { headers, rows: dataRows };
+}
+function pickBestTable($) {
+    const tables = $('table');
+    let best = null;
+    let bestScore = -1;
+    for (let i = 0; i < tables.length; i++) {
+        const tableSel = tables.eq(i);
+        const rows = tableRows(tableSel);
+        if (rows.length === 0)
+            continue; // never selectable — no header even
+        const score = scoreTable(tableSel);
+        // Strict `>` only — ties keep the first table encountered.
+        if (best === null || score > bestScore) {
+            best = tableSel;
+            bestScore = score;
+        }
+    }
+    return best;
+}
+export function extractTable(html, opts) {
+    const $ = load(html);
+    if (opts?.select != null) {
+        const matched = $(opts.select);
+        if (matched.length === 0) {
+            return {
+                headers: [],
+                rows: [],
+                warning: `The selector "${opts.select}" matched no element on the page.`,
+            };
+        }
+        const { headers, rows } = readTable(matched.eq(0));
+        if (headers.length === 0 && rows.length === 0) {
+            return { headers, rows, warning: NO_TABLE_WARNING };
+        }
+        return { headers, rows };
+    }
+    const best = pickBestTable($);
+    if (best === null) {
+        return { headers: [], rows: [], warning: NO_TABLE_WARNING };
+    }
+    return readTable(best);
+}

package/dist/parse/index.d.ts

@@ -0,0 +1,7 @@
+export * from './types.js';
+export * from './parse_number.js';
+export * from './parse_date.js';
+export * from './extract_table.js';
+export * from './map_columns.js';
+export * from './map_rows.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/parse/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/parse/index.ts"],"names":[],"mappings":"AAEA,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC"}

package/dist/parse/index.js

@@ -0,0 +1,7 @@
+// hazo_scrape/src/parse/index.ts — public surface of the pure, network-free parse layer
+export * from './types.js';
+export * from './parse_number.js';
+export * from './parse_date.js';
+export * from './extract_table.js';
+export * from './map_columns.js';
+export * from './map_rows.js';

package/dist/parse/map_columns.d.ts

@@ -0,0 +1,6 @@
+import type { ColumnKeywords, ColumnMap } from './types.js';
+export declare function mapColumns(headers: string[], keywords: ColumnKeywords, opts?: {
+    dateGuard?: boolean;
+    required?: string[];
+}): ColumnMap;
+//# sourceMappingURL=map_columns.d.ts.map

package/dist/parse/map_columns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"map_columns.d.ts","sourceRoot":"","sources":["../../src/parse/map_columns.ts"],"names":[],"mappings":"AAqCA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAa,MAAM,YAAY,CAAC;AAEvE,wBAAgB,UAAU,CACxB,OAAO,EAAE,MAAM,EAAE,EACjB,QAAQ,EAAE,cAAc,EACxB,IAAI,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GAClD,SAAS,CAmCX"}

package/dist/parse/map_columns.js

@@ -0,0 +1,66 @@
+// hazo_scrape/src/parse/map_columns.ts — pure, network-free header-to-column mapping
+//
+// Generalises the divscraper prototype's `mapHeaders` (dividends.mjs, line 150),
+// fixing three bugs baked into that prototype's "first match wins" design:
+//
+//  1. ONE-TO-MANY. The prototype's `if (idx[key] != null) continue;` is exactly
+//     the RIO USD-over-AUD bug: a table with BOTH "Dividend (USD)" and
+//     "Dividend (AUD)" silently took whichever came first. Here every matching
+//     header is returned as a candidate, in header order; a key with 2+
+//     candidates is reported in `ambiguous`. This engine NEVER resolves
+//     ambiguity — the caller (or a human) must.
+//
+//  2. GENERIC dateGuard VIA `type`. The prototype hardcodes
+//     `key !== 'exDate' && key !== 'payDate'`. Here the rule is driven by the
+//     caller-declared `ColumnSpec.type`: when `opts.dateGuard` is on, a header
+//     matching "date" is dropped from the candidate list of any key whose
+//     `type !== 'date'`. So "Ex-Dividend Date" can never become an `amount`
+//     candidate even though it contains the keyword "dividend".
+//
+//  3. CALLER-DECLARED `required` — replaces a magic score threshold. `ok` is
+//     false only when some key listed in `opts.required` has zero candidates.
+//     If `required` is omitted, `ok` is always true.
+//
+// Matching rule (ported from prototype line 161): a header matches a key if
+// the header text, lowercased and trimmed, INCLUDES any of that key's
+// keywords (substring match, not equality). A header may match multiple keys
+// — that is expected and not an error.
+//
+// `matched` ALWAYS contains one entry per key in `keywords`, even when a key
+// has zero candidates (e.g. `franking` on a BHP-style table with no franking
+// column) — the array is simply empty. This lets a caller check
+// `map.matched.franking.length === 0` without an `in` check.
+//
+// `unmatched` holds ORIGINAL-CASE header text for headers that matched NO key
+// at all. It is about HEADERS, not about keys with zero candidates — those
+// live in `matched[key] === []`, not in `unmatched`.
+export function mapColumns(headers, keywords, opts) {
+    const dateGuard = opts?.dateGuard ?? false;
+    const required = opts?.required ?? [];
+    const matched = {};
+    for (const key of Object.keys(keywords))
+        matched[key] = [];
+    const unmatched = [];
+    headers.forEach((header, index) => {
+        const text = header.trim().toLowerCase();
+        const isDateHeader = text.includes('date');
+        let matchedAny = false;
+        for (const [key, spec] of Object.entries(keywords)) {
+            // Guard: a header that reads as a date column may only be claimed by a
+            // date-typed key, even if it also contains another key's keyword
+            // (e.g. "Ex-Dividend Date" contains "dividend").
+            if (dateGuard && isDateHeader && spec.type !== 'date')
+                continue;
+            const isMatch = spec.keywords.some((kw) => text.includes(kw.toLowerCase()));
+            if (isMatch) {
+                matched[key].push({ header, index });
+                matchedAny = true;
+            }
+        }
+        if (!matchedAny)
+            unmatched.push(header);
+    });
+    const ambiguous = Object.keys(keywords).filter((key) => matched[key].length >= 2);
+    const ok = required.every((key) => (matched[key]?.length ?? 0) > 0);
+    return { ok, matched, unmatched, ambiguous, headers };
+}

package/dist/parse/map_rows.d.ts

@@ -0,0 +1,6 @@
+import type { ColumnKeywords, ColumnMap, MappedRow } from './types.js';
+export declare function mapRows(table: {
+    headers: string[];
+    rows: string[][];
+}, map: ColumnMap, keywords: ColumnKeywords): MappedRow[];
+//# sourceMappingURL=map_rows.d.ts.map

package/dist/parse/map_rows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"map_rows.d.ts","sourceRoot":"","sources":["../../src/parse/map_rows.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAQ,cAAc,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAW7E,wBAAgB,OAAO,CACrB,KAAK,EAAE;IAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAA;CAAE,EAC9C,GAAG,EAAE,SAAS,EACd,QAAQ,EAAE,cAAc,GACvB,SAAS,EAAE,CAuBb"}

package/dist/parse/map_rows.js

@@ -0,0 +1,47 @@
+// hazo_scrape/src/parse/map_rows.ts — pure, network-free join of a ColumnMap onto table rows
+//
+// mapColumns decides WHICH header(s) mean what; this module reads the actual
+// raw string out of each data row for every matched candidate and parses it
+// per the key's declared ColumnSpec.type, producing the approved one-to-many
+// row shape: Record<string, Cell[]>.
+//
+// Iteration is driven off `map.matched` — that is the authority on what
+// matched (mapColumns guarantees every key in `keywords` is present, even
+// with an empty array). `keywords` is only consulted for `.type`. If a key
+// present in `map.matched` is somehow absent from `keywords` (should not
+// happen in practice since both are keyed off the same caller-declared
+// keyword map), its type defensively falls back to 'text'.
+//
+// Ragged rows (shorter than a candidate's index) never throw: the raw string
+// is treated as '' and value is computed from that empty string (null for
+// number/date, null for text after trim). Rows are taken as-is, never padded.
+import { parseNumber } from './parse_number.js';
+import { parseDate } from './parse_date.js';
+function cellValue(type, raw) {
+    if (type === 'number')
+        return parseNumber(raw);
+    if (type === 'date')
+        return parseDate(raw);
+    const trimmed = raw.trim();
+    return trimmed === '' ? null : trimmed;
+}
+export function mapRows(table, map, keywords) {
+    const keys = Object.keys(map.matched);
+    return table.rows.map((row) => {
+        const mappedRow = {};
+        for (const key of keys) {
+            const candidates = map.matched[key] ?? [];
+            const type = keywords[key]?.type ?? 'text';
+            mappedRow[key] = candidates.map((candidate) => {
+                const raw = row[candidate.index] ?? '';
+                return {
+                    header: candidate.header,
+                    index: candidate.index,
+                    raw,
+                    value: cellValue(type, raw),
+                };
+            });
+        }
+        return mappedRow;
+    });
+}

package/dist/parse/parse_date.d.ts

@@ -0,0 +1,4 @@
+export declare function parseDate(raw: string, opts?: {
+    formats?: string[];
+}): string | null;
+//# sourceMappingURL=parse_date.d.ts.map

package/dist/parse/parse_date.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse_date.d.ts","sourceRoot":"","sources":["../../src/parse/parse_date.ts"],"names":[],"mappings":"AA6EA,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,MAAM,GAAG,IAAI,CAoCnF"}

package/dist/parse/parse_date.js

@@ -0,0 +1,112 @@
+// hazo_scrape/src/parse/parse_date.ts — pure, network-free date-cell parsing
+//
+// Always returns ISO "yyyy-mm-dd" or null. Never returns the raw input.
+//
+// DEVIATION from the divscraper prototype (dividends.mjs parseDate):
+//   - unrecognised input returns null, never the raw string.
+//   - ambiguous slash dates (e.g. "05/03/2026") return null rather than
+//     blindly assuming day-first. Slash dates are only resolved without a
+//     hint when one ordering is calendar-impossible (a component > 12), or
+//     when the caller supplies `opts.formats` to disambiguate.
+const MONTHS = {
+    jan: 1,
+    feb: 2,
+    mar: 3,
+    apr: 4,
+    may: 5,
+    jun: 6,
+    jul: 7,
+    aug: 8,
+    sep: 9,
+    oct: 10,
+    nov: 11,
+    dec: 12,
+};
+function isLeapYear(year) {
+    return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+}
+function daysInMonth(year, month) {
+    const lengths = [31, isLeapYear(year) ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+    return lengths[month - 1] ?? 0;
+}
+function toIsoIfValid(year, month, day) {
+    if (!Number.isInteger(year) || !Number.isInteger(month) || !Number.isInteger(day))
+        return null;
+    if (month < 1 || month > 12)
+        return null;
+    if (day < 1)
+        return null;
+    if (day > daysInMonth(year, month))
+        return null;
+    const y = String(year).padStart(4, '0');
+    const mo = String(month).padStart(2, '0');
+    const d = String(day).padStart(2, '0');
+    return `${y}-${mo}-${d}`;
+}
+function monthFromName(name) {
+    const key = name.toLowerCase().slice(0, 3);
+    return MONTHS[key] ?? null;
+}
+function pickSlashHint(formats) {
+    if (!formats)
+        return undefined;
+    for (const f of formats) {
+        if (f === 'DD/MM/YYYY' || f === 'MM/DD/YYYY')
+            return f;
+    }
+    return undefined;
+}
+function resolveSlashDate(a, b, year, formats) {
+    const hint = pickSlashHint(formats);
+    if (hint === 'DD/MM/YYYY')
+        return toIsoIfValid(year, b, a);
+    if (hint === 'MM/DD/YYYY')
+        return toIsoIfValid(year, a, b);
+    // No hint: only resolve when the ordering is unambiguous, i.e. exactly one
+    // of the two components is impossible as a month (> 12). Never guess.
+    const aCanBeMonth = a <= 12;
+    const bCanBeMonth = b <= 12;
+    if (aCanBeMonth && bCanBeMonth)
+        return null; // ambiguous — never guess
+    if (!aCanBeMonth && bCanBeMonth)
+        return toIsoIfValid(year, b, a); // a is day, b is month
+    if (aCanBeMonth && !bCanBeMonth)
+        return toIsoIfValid(year, a, b); // b is day, a is month
+    return null; // neither can be a month — not a valid date
+}
+export function parseDate(raw, opts) {
+    if (raw == null)
+        return null;
+    const s = String(raw).trim();
+    if (s === '')
+        return null;
+    // ISO: yyyy-mm-dd
+    let m = s.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+    if (m) {
+        return toIsoIfValid(Number(m[1]), Number(m[2]), Number(m[3]));
+    }
+    // "D Mon YYYY" / "D Month YYYY", e.g. "5 Mar 2026", "18 November 2025"
+    m = s.match(/^(\d{1,2})\s+([A-Za-z]{3,})\s+(\d{4})$/);
+    if (m) {
+        const month = monthFromName(m[2]);
+        if (month == null)
+            return null;
+        return toIsoIfValid(Number(m[3]), month, Number(m[1]));
+    }
+    // "Mon D, YYYY" / "Month D YYYY", comma optional, e.g. "Mar 5, 2026"
+    m = s.match(/^([A-Za-z]{3,})\s+(\d{1,2}),?\s+(\d{4})$/);
+    if (m) {
+        const month = monthFromName(m[1]);
+        if (month == null)
+            return null;
+        return toIsoIfValid(Number(m[3]), month, Number(m[2]));
+    }
+    // Slash dates: D/M/Y or M/D/Y — ambiguous without a hint or a proof by
+    // calendar impossibility (see resolveSlashDate). Two-digit years are
+    // intentionally rejected: the year group below requires exactly 4 digits.
+    m = s.match(/^(\d{1,2})\/(\d{1,2})\/(\d{4})$/);
+    if (m) {
+        return resolveSlashDate(Number(m[1]), Number(m[2]), Number(m[3]), opts?.formats);
+    }
+    return null;
+}

package/dist/parse/parse_number.d.ts

@@ -0,0 +1,2 @@
+export declare function parseNumber(raw: string): number | null;
+//# sourceMappingURL=parse_number.d.ts.map

package/dist/parse/parse_number.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse_number.d.ts","sourceRoot":"","sources":["../../src/parse/parse_number.ts"],"names":[],"mappings":"AAaA,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAqBtD"}

package/dist/parse/parse_number.js

@@ -0,0 +1,31 @@
+// hazo_scrape/src/parse/parse_number.ts — pure, network-free numeric-cell parsing
+//
+// Strips currency symbols, currency codes, thousands separators, "%" and
+// whitespace, then parses what remains as a plain JS number.
+//
+// DEVIATION from the divscraper prototype (dividends.mjs parseAmount/parseFranking):
+// this function does NOT apply any domain-specific reinterpretation of the
+// number. In particular:
+//   - no cents->dollars conversion ("looksLikeCents" heuristic) — "280" stays 280.
+//   - no franking-specific text mapping ("Unfranked" -> 0, "Fully franked" -> 100).
+// Anything with no parseable digits returns null. Domain interpretation belongs
+// in the caller, not in this generic engine.
+export function parseNumber(raw) {
+    if (raw == null)
+        return null;
+    let s = String(raw).trim();
+    if (s === '')
+        return null;
+    // Strip currency symbols (e.g. $, £, €, ¥, ¢, ₹, ₩, ...).
+    s = s.replace(/\p{Sc}/gu, '');
+    // Strip 3-letter uppercase currency codes (e.g. AUD, USD, EUR).
+    s = s.replace(/\b[A-Z]{3}\b/g, '');
+    // Strip thousands separators and percent signs.
+    s = s.replace(/,/g, '');
+    s = s.replace(/%/g, '');
+    s = s.trim();
+    if (s === '')
+        return null;
+    const num = Number(s);
+    return Number.isFinite(num) ? num : null;
+}

package/dist/parse/types.d.ts

@@ -0,0 +1,24 @@
+export type ColumnSpec = {
+    keywords: string[];
+    type: 'number' | 'date' | 'text';
+};
+export type ColumnKeywords = Record<string, ColumnSpec>;
+export type Candidate = {
+    header: string;
+    index: number;
+};
+export type ColumnMap = {
+    ok: boolean;
+    matched: Record<string, Candidate[]>;
+    unmatched: string[];
+    ambiguous: string[];
+    headers: string[];
+};
+export type Cell = {
+    header: string;
+    index: number;
+    raw: string;
+    value: number | string | null;
+};
+export type MappedRow = Record<string, Cell[]>;
+//# sourceMappingURL=types.d.ts.map

package/dist/parse/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/parse/types.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,UAAU,GAAG;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAA;CAAE,CAAC;AAClF,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AACxD,MAAM,MAAM,SAAS,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAC1D,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;IACrC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AACF,MAAM,MAAM,IAAI,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AACjG,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC"}

package/dist/parse/types.js

@@ -0,0 +1,2 @@
+// hazo_scrape/src/parse/types.ts — public types for the pure, network-free parse layer
+export {};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "hazo_scrape",
+  "version": "1.0.1",
+  "description": "Generic source-agnostic web scraping engine with a network-free parse core.",
+  "type": "module",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./parse": {
+      "types": "./dist/parse/index.d.ts",
+      "import": "./dist/parse/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGE_LOG.md",
+    "SETUP_CHECKLIST.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "type-check": "tsc --noEmit",
+    "lint": "tsc --noEmit",
+    "test": "node --experimental-vm-modules ../node_modules/jest/bin/jest.js --config jest.config.cjs",
+    "dev:test-app": "npm run build && cd test-app && npm run dev",
+    "build:test-app": "npm run build && cd test-app && npm run build"
+  },
+  "peerDependencies": {
+    "hazo_core": "^1.0.1",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.10.0",
+    "jest": "^30.2.0",
+    "jest-environment-node": "^30.2.0",
+    "ts-jest": "^29.4.5",
+    "typescript": "^5.7.2"
+  },
+  "keywords": [],
+  "author": "Pubs Abayasiri",
+  "license": "MIT",
+  "dependencies": {
+    "cheerio": "^1.2.0"
+  }
+}