@toolpath/tool-scraper 0.1.0 → 2.0.0

package/dist/vendors/maritool/scrape.d.ts

@@ -0,0 +1,297 @@
+/**
+ * MariTool category listings -> toolholding rows.
+ *
+ * The fifth vendor and the first whose transport needed no discovery at all:
+ * `www.maritool.com` is an osCommerce-family storefront that server-renders
+ * everything, so the whole transport is a paced `GET`. There is no JSON API,
+ * no sitemap and no application bundle to read — see
+ * `docs/MARITOOL_CATALOG.md` for what was tried and what the tree looks like.
+ *
+ * ## Two sources, and both are needed
+ *
+ * **The roster** is a leaf category's listing page. Every row carries the
+ * part number (`Part#:`), the store's `products_id`, the product name and the
+ * CAD assets, and the page states its own row total — `(of 51 products)` —
+ * which is the second opinion `receipts.checkRows` gets for free from a
+ * hand-counted `rows` and which nothing here computes from the rows it just
+ * collected.
+ *
+ * **The geometry** is a `Product Specifications` name/value table on each
+ * part's own page, so this is one request per part. The table's labels are
+ * MariTool's own and are carried into the CSV verbatim, which is the standing
+ * rule; the header is their union in first-seen order, because which keys a
+ * part publishes is a function of its style. A shrink-fit holder states
+ * `Shank Size` and `Nose Diameter`, a collet chuck states `Collet Size` and
+ * `Collet Grip Range`, and a hydraulic chuck states `Hydraulic Type`.
+ *
+ * ## What the vendor gets wrong
+ *
+ * Four faults found on 2026-08-29, all reported as warnings rather than
+ * fixed — two disagreeing vendor cells cannot say which one is wrong, and a
+ * scraper that corrects one becomes a place tool data is authored by hand.
+ * This is the same call `vendors/regofix/scrape.ts` made on its three.
+ *
+ * 1. **`BT40-ER32-60` publishes no `Taper` row at all**, alone among the 529
+ *    parts in scope. Its row is kept with `taper` and `contact` empty rather
+ *    than dropped or filled in from its part number: the CSV is a receipt, and
+ *    the hole is what the vendor published.
+ * 2. **`Collet Size` carries a collet *nut* designation on two parts.**
+ *    `CAT40-ER25-3.0MD` and `BT30-ER25-60M` both state `ER25M`, and `ER25M` is
+ *    not a collet series — `HSK40E-ER16-3.0M` puts exactly that shape of value
+ *    in its own `Collet Nut` cell, which is the column it belongs in. The
+ *    string is written into `CST` as designated, so it joins to no collet
+ *    family, and it is warned about. Widening it to `ER25` would offer a
+ *    machinist a collet that may not seat.
+ * 3. **`Collet Size` is spaced inconsistently within one style** — `ER 11`
+ *    and `ER11` are both published. {@link colletSeries} closes the space,
+ *    because `CST` is a join key and two spellings of one series join to
+ *    nothing.
+ * 4. **Two parts publish no `Product Specifications` table**, both in the
+ *    CAT50 `Collet Chucks` leaf. They state their geometry as English prose in
+ *    a `Product Info` bullet list instead — *"Gage length is 100mm (3.93
+ *    inch)"* — and that is a sentence, not a table. They are skipped with a
+ *    named warning; a regex over the prose would be this package authoring
+ *    tool data by hand.
+ *
+ * ## Where the units are
+ *
+ * `Gage Length` is metric on some parts and imperial on others **inside one
+ * CSV, and inside one category page**: `HSK40E-ER11-40` gages `40mm` where
+ * `HSK40E-ER16-3.0M` gages `3.0` inches, and both are rows of
+ * `c23_46_1552_1558`. So no MariTool family declares a `unit`, and the gage
+ * length is promoted into an `L1_in`/`L1_mm` pair with exactly one cell filled
+ * — the shape `regofix.colletRow` already gives `Square_in`/`Square_mm`.
+ *
+ * **Nothing is converted.** The vendor's own imperial conversion is unusable
+ * (its prose calls 40 mm "1.6 inches" where the figure is 1.5748), and
+ * computing one here would put a number in the file that the vendor never
+ * published. The raw `Gage Length` cell is kept beside the pair.
+ *
+ * Every other measured cell — `Shank Size`, `Nose Diameter`, `Collet Grip
+ * Range` — stays verbatim under MariTool's own label, unsuffixed and
+ * unpromoted. That is deliberate: `conventions.dimensionalColumn` takes its
+ * suffix from a family's declared `unit`, and these families have none to give
+ * it. An adapter choosing `_in` for those cells itself is exactly the mistake
+ * a declared `unit` exists to prevent, and `HSK40E-SF.125-45` is the row that
+ * proves it — gaged in millimetres, bored in inches.
+ */
+import { type UnitSystem } from '../../conventions.js';
+import type { Fetcher } from '../../fetch.js';
+import { type ScrapeResult, type ScrapedRow, type Warn } from '../../scrape.js';
+export declare const BASE = "https://www.maritool.com";
+/**
+ * The CSV columns this adapter builds rather than lifts from a spec table.
+ *
+ * `products_id` is the store's internal id and an ordinary column: a
+ * re-created product would change it, and every guid minted off it with it —
+ * which is why identity is the part number. It is carried anyway because it is
+ * what a re-fetch of one part is addressed by.
+ */
+export declare const MATERIAL_COLUMN = "Material Number";
+export declare const STORE_ID_COLUMN = "products_id";
+export declare const TAPER_COLUMN = "taper";
+export declare const CLAMPING_COLUMN = "clamping";
+export declare const STYLE_COLUMN = "style";
+/** MariTool's own label for the cell `conventions.GAGE_COLUMNS` is promoted from. */
+export declare const GAGE_LABEL = "Gage Length";
+/** MariTool's own label for the cell {@link COLLET_SERIES_COLUMN} comes from. */
+export declare const COLLET_SIZE_LABEL = "Collet Size";
+/** MariTool's own label for the cell {@link TAPER_FORMS} is looked up by. */
+export declare const TAPER_LABEL = "Taper";
+/**
+ * Every `Taper` cell this package is willing to read, and what it means.
+ *
+ * A closed table rather than a pattern, and keyed on the cell upper-cased
+ * because MariTool publishes the dual-contact suffix in two casings
+ * (`CAT50 DUAL CONTACT` and `CAT50 Dual Contact` are both in the catalog). An
+ * unlisted value throws naming itself: a spindle interface this package cannot
+ * name is a guess about which machine a holder fits, which is the call
+ * `regofix.CONTACT_BY_FORM` made on `BT-OM 30`.
+ *
+ * **`contact` is `face` on every HSK size, and MariTool does not say so.** It
+ * is the interface's definition rather than a property of the part: an HSK
+ * shank is a hollow taper that seats on the flange face at the same time as
+ * the cone, which is what DIN 69893 / ISO 12164 specify and what the `A`, `E`
+ * and `F` forms vary the flange of rather than the contact. MariTool marks
+ * `DUAL CONTACT` only on its 7/24 tapers, where it is an option, and there is
+ * nothing to mark on an HSK because there is no single-contact HSK to
+ * distinguish it from.
+ */
+export declare const TAPER_FORMS: Record<string, {
+    taper: string;
+    contact: string;
+}>;
+/**
+ * One leaf category to scrape, and how MariTool classifies what is in it.
+ *
+ * **`clamping` and `style` come from the leaf, not from a family constant.**
+ * Each of the five CSVs is one taper and mixes all three holder styles, so
+ * neither can be a family fact; and the leaf name is MariTool's own
+ * classification of the part, so the column is vendor-stated rather than a
+ * coinage. The values live in `families/maritool.ts` beside the cPath they
+ * come from.
+ *
+ * Declared here and re-declared structurally by the config table rather than
+ * imported from it, because `families/` must not import an adapter and an
+ * adapter must not import the config — `tests/vendor-boundary.test.ts` refuses
+ * both directions.
+ */
+export interface LeafTarget {
+    /** MariTool's own category path, e.g. `23_25_42`. */
+    readonly cPath: string;
+    /** How a holder in this leaf grips: `collet`, `shrink`, `hydraulic`. */
+    readonly clamping: string;
+    /** The product style, as MariTool names the leaf: `er-collet-chuck`. */
+    readonly style: string;
+}
+/** One row of a leaf's listing, before its product page has been read. */
+export interface ListingRow {
+    /** The store's internal id, from the product link. */
+    readonly productsId: string;
+    /** The `Part#:` line — the identity, and the guid seed. */
+    readonly partNumber: string;
+    /** The vendor's own product name, which is where a nose form survives. */
+    readonly name: string;
+    /** The vendor's own link to this part's page. */
+    readonly productUrl: string;
+    /** Downloadable assets by their own code — `STP`, `DXF`, `DWG`, `PDF`. */
+    readonly assets: Readonly<Record<string, string>>;
+}
+/** One listing page: the vendor's row total, and the rows it rendered. */
+export interface Listing {
+    /** What `(of N products)` said. The whole leaf, not this page. */
+    readonly total: number;
+    readonly rows: ListingRow[];
+}
+/** One product page: its spec table, and what its downloads header calls it. */
+export interface Product {
+    /** MariTool's own labels to its own values. Empty where none is published. */
+    readonly specs: Record<string, string>;
+    /**
+     * The part number the downloads header restates, or null where the part
+     * publishes no assets and so carries no header.
+     */
+    readonly statedPartNumber: string | null;
+}
+/**
+ * A leaf category's listing page.
+ *
+ * The slug in a rewritten URL is ignored by the store, so this uses the
+ * platform's own unrewritten form and invents no slug: three URL forms reach
+ * the same page and only this one is derivable from a cPath alone.
+ */
+export declare function categoryUrl(cPath: string, page?: number): string;
+/**
+ * One listing page's roster row total and its rendered rows.
+ *
+ * The rows are read off `<tr class="product-info">`, which is the vendor's own
+ * marker for one, and the store id off the product link rather than off the
+ * add-to-cart form's hidden input: the link is the first thing in the row and
+ * is also what the next request needs.
+ */
+export declare function parseListing(html: string): Listing;
+/** Options every MariTool scrape accepts. */
+export interface MaritoolOptions {
+    warn?: Warn;
+    /** Milliseconds between requests. Zero in a test, {@link REQUEST_DELAY_MS} live. */
+    delayMs?: number;
+}
+/**
+ * Every part in one leaf category, paged until the vendor's own count is met.
+ *
+ * **The count is the gate, and it is the vendor's rather than ours.** A roster
+ * that stopped a page early is the failure this package is built to notice,
+ * and it cannot be noticed by counting the rows that were collected — that
+ * number agrees with itself. `(of N products)` is a second opinion the store
+ * computes from its own database, which is the check `regofix.search` gets
+ * free from `hits.total`.
+ *
+ * A page that adds no new row stops the walk rather than looping: a paging
+ * parameter the store has stopped honouring answers with page 1 forever.
+ */
+export declare function roster(fetcher: Fetcher, cPath: string, options?: MaritoolOptions): Promise<ListingRow[]>;
+/**
+ * One product page's `Product Specifications` table and downloads header.
+ *
+ * Both are found by their own `<div class="header">` rather than positionally,
+ * because a page carries several such blocks and which ones are present varies
+ * — 2 of the 529 parts in scope publish no spec table and roughly one in four
+ * publishes no downloads.
+ *
+ * An empty `specs` is a real state and is not an error here: the caller is
+ * what decides that a part with no geometry is skipped rather than written
+ * with holes.
+ */
+export declare function parseProduct(html: string): Product;
+/** One part's page, fetched through the seam every transport here uses. */
+export declare function fetchProduct(fetcher: Fetcher, url: string): Promise<Product>;
+/** A gage length, read off the cell the vendor printed it in. */
+export interface GageLength {
+    readonly value: number;
+    readonly unit: UnitSystem;
+}
+/**
+ * A `Gage Length` cell as a number and the unit system it is stated in.
+ *
+ * **A bare number is inches.** That is the vendor's convention rather than
+ * this package guessing: MariTool marks every metric cell `mm` and marks
+ * nothing on an imperial one — 363 of the 473 in-scope cells sampled are bare
+ * or carry an inch mark, and a gage length of "3.0" millimetres is not a
+ * holder. The part number says nothing about it either way: `HSK40E-ER11-40`
+ * is millimetres and `HSK40E-ER16-3.0M` is inches, where that `M` is a mini
+ * nut.
+ *
+ * **The nose form is parsed off and given no column.** `120mm Tapered` is 120
+ * millimetres, and `Tapered` is not a data type — it is not lost, because the
+ * vendor states it in the product name too (*"BT40 ER11 120mm Tapered Nose
+ * Collet Chuck Tool Holder"*), and the row carries that name verbatim in
+ * `Description`. The raw cell stays in the CSV as well.
+ *
+ * Refused rather than returned as `NaN`, the rule `regofix.parseSize` holds: a
+ * cell this cannot read would otherwise travel into a row as a gage length.
+ */
+export declare function parseGageLength(cell: string): GageLength;
+/**
+ * A `Collet Size` cell as the series `CST` joins a collet family on.
+ *
+ * Only the spacing is closed. MariTool publishes `ER 11` and `ER11` within one
+ * style, and two spellings of one series join to nothing — `CST` is the key
+ * `families/kennametal.ts` states the holder-to-collet join against, and the
+ * collet side of it spells the series without a space.
+ *
+ * Nothing else is normalised. `ER25M` is written through as designated even
+ * though no such collet series exists, because the alternative is to decide on
+ * the vendor's behalf that its `M` is the mini nut its `Collet Nut` column
+ * carries elsewhere — see this module's docstring. {@link holderRow} warns.
+ */
+export declare function colletSeries(cell: string): string;
+/**
+ * One listing row plus its spec table -> one CSV row.
+ *
+ * The vendor's own labels are carried verbatim and in the order the page
+ * states them; what this adds in front of them is the four axes the catalog
+ * asks a holder about — `taper`, `contact`, `clamping`, `style` — plus the
+ * collet series and the promoted gage length.
+ *
+ * **No bore column.** A collet chuck grips through a collet and a shrink-fit
+ * holder's bore is stated under MariTool's own `Shank Size` label; promoting
+ * either to `D1` would make a collet-clamping holder claim a clamping capacity
+ * of its own, which is the reason `regofix.holderRow` has no `D1` either. For
+ * the same reason `Collet Grip Range` is carried verbatim and never becomes
+ * `CCCN`/`CCCX`: it is the ER series' range restated on the holder's page, a
+ * pure function of `Collet Size` across every part sampled, and a real one
+ * comes from a collet family joined on `CST`.
+ */
+export declare function holderRow(leaf: LeafTarget, listing: ListingRow, specs: Readonly<Record<string, string>>, warn?: Warn): ScrapedRow;
+/**
+ * Every in-scope holder under `leaves`, one CSV's worth.
+ *
+ * One request per leaf page for the roster, then one per part for its
+ * geometry, paced by the package's shared politeness delay throughout.
+ *
+ * **Deduped by `products_id` across leaves.** MariTool lists a handful of
+ * parts under two leaves, and a part is one row however many places the store
+ * files it. The first leaf to reach it wins, which is what makes the row
+ * order below independent of which duplicate was found.
+ */
+export declare function scrapeHolders(fetcher: Fetcher, leaves: readonly LeafTarget[], options?: MaritoolOptions): Promise<ScrapeResult>;