@toolpath/tool-scraper 0.1.0

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

@@ -0,0 +1,237 @@
+/**
+ * REGO-FIX powRgrip product index -> toolholding rows.
+ *
+ * Nothing here is shared with any other adapter beyond `conventions` —
+ * REGO-FIX is a Drupal site, not Kennametal's AEM platform, so the transport,
+ * the identity fields and the dimension source are all different. See
+ * `docs/REGOFIX_PRODUCTFINDER_API.md` for how the endpoint was found.
+ *
+ * ## Two sources, and both are needed
+ *
+ * **The roster** comes from the ProductFinder's Elasticsearch proxy: one POST
+ * returns every variant of a group with its part number, its designation, its
+ * PG series and its CAD links. It carries no geometry beyond the projection
+ * length.
+ *
+ * **The geometry** comes from a per-part DIN 4000 XML on the vendor's CDN,
+ * linked from each hit. Three of its codes are pinned to a meaning by
+ * REGO-FIX's own published tables and the rest are not:
+ *
+ * - **`B3`** — projection from the flange face. The `L` column of the BT/PG
+ *   table in the PG product catalog, row for row.
+ * - **`B4`** — gage length. `B4 - B3 == 48.4` on every row, and 48.4 mm is
+ *   BT 30's gauge-line-to-flange distance in the vendor's own standards table.
+ * - **`A1`** — diameter at the collet end. The `D` column of that same BT/PG
+ *   table, row for row.
+ *
+ * `A2`, `B1`, `B2` and `B3_WOA` are carried into the CSV verbatim under their
+ * raw DIN codes and are **not** promoted onto a record. Nothing available here
+ * says what they measure, and the standing rule is to leave a vendor code
+ * unlabelled rather than guess at it (JG 2026-08-07). `conventions.DIN_PREFIX`
+ * is what keeps them from reading as promoted dimensions: a column named
+ * `A2_mm` would sit in the CSV looking exactly like `L1_mm`, which is mapped.
+ *
+ * There is a lead on pinning them honestly. REGO-FIX publishes
+ * `DXF_ISO13399/DXF` and `DXF_ISO13399/PDF` beside the `XML_DIN4000/XML` this
+ * module reads, so the standard this package's canonical names come from is
+ * already in the vendor's own source material.
+ *
+ * `A4` is 46 on every BT 30 holder — the flange diameter, a property of the
+ * taper and not of the part — so it is checked rather than stored.
+ *
+ * ## What the vendor gets wrong
+ *
+ * Three faults found on 2026-08-07, 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.
+ *
+ * 1. `4130.70646`'s XML states its own part number as `4130.71646`.
+ * 2. `J22`, the XML's own product-line label, says "PG-SG secuRgrip
+ *    Werkzeughalter" on several plain BT 30 holders that are not secuRgrip
+ *    parts. It is never read.
+ * 3. `o_mm` on a tapping collet repeats the previous row's value twice
+ *    (`1715.08215` and `1725.08215`). This is why the nominal size is parsed
+ *    from the vendor's own designation and `o_mm` is only ever a cross-check.
+ */
+import { type Fetcher } from '../../fetch.js';
+import { type ScrapeResult, type ScrapedRow, type Warn } from '../../scrape.js';
+export declare const MM_PER_INCH = 25.4;
+/**
+ * The Searchkit proxy the ProductFinder posts its Elasticsearch queries to.
+ * Discovered by reading the app bundle, which constructs
+ * `SearchkitManager(origin + '/' + lang, {searchUrlPath: '/elastic/post'})`.
+ */
+export declare const SEARCH_URL = "https://us.rego-fix.com/en/elastic/post";
+/**
+ * Where a part's DIN 4000 XML lives. The filename is the part number with its
+ * dot removed, which is also `field_sku_ngram`.
+ */
+export declare const DIN4000_URL: string;
+/**
+ * Gauge line to flange face, JIS B 6339 / MAS 403 size 30, as published in the
+ * vendor's own interface table (PG product catalog, "BT MAS 403":
+ * `BT 30 | 31.75 | 46 | 2 | 48.4 | 20 | M 12`). Used to *verify* that `B4` is
+ * the gage length rather than to compute one — both numbers are scraped, and
+ * their difference is what identifies the code.
+ */
+export declare const BT30_GAUGE_TO_FLANGE = 48.4;
+/** Flange diameter of a BT 30 taper, from the same row. `A4` on every holder. */
+export declare const BT30_FLANGE_DIAMETER = 46;
+/**
+ * DIN 4000 codes carried into the CSV verbatim because nothing here says what
+ * they measure. Written out rather than "everything else" so that a code the
+ * vendor adds later shows up as an unhandled key instead of silently appearing
+ * as a column.
+ */
+export declare const UNPINNED_DIN_CODES: readonly ["A2", "B1", "B2", "B3_WOA"];
+/**
+ * `form_name`, the vendor's own field, mapped to this catalog's `contact`
+ * axis. `Plus +` is REGO-FIX's designation for the dual-contact shank that
+ * seats on the spindle face as well as the cone — the same distinction
+ * Kennametal sells as BTKV. It is a **scraped fact here**, not family config,
+ * because REGO-FIX publishes both forms in one product group:
+ * `BT 30 / PG 25 x 080 H` and `BT+ 30 / PG 25 x 080 H` are two rows of one
+ * table.
+ *
+ * There is no default. A third form is a stop-and-ask, and `BT-OM 30` is
+ * already sitting in that table undefined — nothing on the vendor's site or in
+ * its catalog says what OM designates, so its three parts are deliberately not
+ * scraped (JG 2026-08-07).
+ */
+export declare const CONTACT_BY_FORM: Record<string, string>;
+/**
+ * The taper designations this package scrapes, and what they mean.
+ *
+ * `BT-OM 30` is published in the same product group and is **not** here: the
+ * family page, the product catalog and the ProductFinder all print the token
+ * and none of them says what OM designates, so recording a spindle interface
+ * for it would be a guess about which machine a holder fits (JG 2026-08-07).
+ * Its three parts are a stop-and-ask, not an omission to fix silently.
+ */
+export declare const SCRAPED_TAPERS: readonly ["BT 30", "BT+ 30"];
+/** One Elasticsearch `_source`: every value is a list, even a single one. */
+export type Source = Record<string, unknown>;
+/**
+ * Every `_source` matching an AND of term filters, newest index first.
+ *
+ * One request: the index holds 4142 products in total and the largest group
+ * asked for here is 321, so there is nothing to page. `size` is an explicit
+ * ceiling rather than a page length, and going over it throws — a silently
+ * truncated roster is the failure this whole package is built to notice.
+ */
+export declare function search(fetcher: Fetcher, filters: Record<string, string>, size?: number): Promise<Source[]>;
+/**
+ * A field of an Elasticsearch `_source`, which stores every value as a list
+ * even when there is exactly one.
+ *
+ * Missing and empty are both null: `o_inch` is absent on a metric collet,
+ * which is the vendor saying it is metric rather than a gap.
+ */
+export declare function one(source: Source, field: string): string | number | null;
+/**
+ * DIN 4000 property codes to their values, empty ones dropped.
+ *
+ * The document repeats a `<PropertyName>`/`<Value>` pair per property and
+ * states most of them empty, so dropping blanks is what makes "the vendor
+ * published this" and "the vendor published a hole" different states.
+ *
+ * Throws on a document with no properties at all rather than returning an
+ * empty map, for the reason `kennametal.parseVariantTable` throws on an
+ * unparseable response: reporting a changed format as no data looks exactly
+ * like a discontinued part.
+ */
+export declare function parseDin4000(xml: string): Record<string, string>;
+/**
+ * One part's DIN 4000 properties, or null when the vendor publishes none.
+ *
+ * Null is a real state — two of the BT+ 30 holders have DXF and PDF but no XML
+ * — and it is distinguished from a failed request, which throws. A holder with
+ * no XML has no gage length and cannot be converted, so it is the caller that
+ * decides what to do about it.
+ */
+export declare function fetchDin4000(fetcher: Fetcher, sku: string): Promise<Record<string, string> | null>;
+/**
+ * A number as the vendor would print it: no trailing `.0` on an integer.
+ *
+ * The CSV is read back as a number, so this only decides what a human and a
+ * git diff see — and `10` rather than `10.0` is what the vendor's own
+ * designation says.
+ */
+export declare function plain(value: string | number | null | undefined): string;
+/** `1/4` or `3.5` — the vendor prints both, and both are exact here. */
+export declare function parseSize(size: string): number;
+/**
+ * The part's STEP model, absolute, or empty when none is published.
+ *
+ * The index gives protocol-relative CDN URLs, and `conventions.CAD_COLUMN`
+ * holds a URL a consumer can fetch — so the scheme is added here rather than
+ * left for every reader to guess at.
+ */
+export declare function cadUrl(source: Source): string;
+/**
+ * One search hit plus its DIN 4000 properties -> one row.
+ *
+ * Column names are the shared toolholding vocabulary rather than REGO-FIX's
+ * own, so a consumer reads a REGO-FIX holder exactly as it reads a Kennametal
+ * one — `L1` is the gage length whoever published it. The DIN codes those came
+ * from are in this module's docstring; the ones that stay unmapped keep their
+ * raw code behind `conventions.DIN_PREFIX`.
+ *
+ * **This is the one place a REGO-FIX label is rewritten, and it is a
+ * holder-geometry label rather than an identity or a dimension code.** The
+ * identity columns are Kennametal's, adopted here because this vendor came
+ * second — see `conventions.IDENTITY_COLUMNS`.
+ *
+ * `D1` is deliberately absent. A powRgrip holder clamps through a collet, and
+ * a collet-clamping holder that also carried a bore would be claiming two ways
+ * of gripping one tool.
+ */
+export declare function holderRow(source: Source, properties: Record<string, string>, warn?: Warn): ScrapedRow;
+/**
+ * One search hit -> one row, with the nominal size read off the vendor's own
+ * designation.
+ *
+ * **The size comes from the title, not from `o_mm`.** `o_mm` is rounded to two
+ * decimals, which puts a 1/8 in collet at 3.18 mm where the part is 3.175 —
+ * five microns out, against the two-micron tolerance a fit test sizes its
+ * equality to, so every inch collet would have failed to match its own shank
+ * size. It is also wrong outright on two tapping collets, where it repeats the
+ * previous row's value. The title states the vendor's designation exactly
+ * (`Ø 1/4"`, `Ø 3.5 mm`) and says which unit system it is in, so it is both
+ * more precise and the only source here that carries a unit at all.
+ *
+ * `o_mm` is kept as a cross-check column rather than dropped, the same way
+ * Kennametal's contradictory unit cells are kept: it is what the vendor said.
+ */
+export declare function colletRow(source: Source, warn?: Warn): ScrapedRow;
+/**
+ * Rows to a result whose header is the union of their keys, in first-seen
+ * order.
+ *
+ * A union rather than the first row's keys: a mixed-unit collet family has
+ * `D1_mm` on its metric rows and `D1_in` on its inch ones, and keying off row
+ * one would drop whichever came second.
+ */
+export declare function unionHeader(rows: readonly ScrapedRow[]): string[];
+/** Options every REGO-FIX scrape accepts. */
+export interface RegofixOptions {
+    warn?: Warn;
+}
+/**
+ * Every powRgrip holder of `group` whose taper is in {@link SCRAPED_TAPERS}.
+ *
+ * Two requests' worth of work per part — the roster is one POST, then one DIN
+ * 4000 document each. A part the vendor publishes no XML for is dropped with a
+ * message rather than written with holes: a gage length is required, and a
+ * holder without one fails conversion anyway.
+ */
+export declare function scrapeHolders(fetcher: Fetcher, group?: string, category?: string, options?: RegofixOptions): Promise<ScrapeResult>;
+/**
+ * Every powRgrip collet of one product group, in the given PG sizes.
+ *
+ * `sizes` are the vendor's `norm_size` values — the PG series numbers a BT 30
+ * holder can take. It is an argument rather than "all of them" because the
+ * sizes are what tie a collet family to the holders in this catalog: PG 32 and
+ * PG 48 collets exist and no BT 30 holder accepts one.
+ */
+export declare function scrapeCollets(fetcher: Fetcher, group: string, sizes: readonly string[], options?: RegofixOptions): Promise<ScrapeResult>;