@toolpath/tool-scraper 0.1.0 → 2.1.0

package/dist/scrape.js

@@ -13,6 +13,30 @@
 export const consoleWarn = (message) => {
     console.warn(message);
 };
+/**
+ * Rows to the header they imply: the union of their keys, in first-seen order.
+ *
+ * A union rather than the first row's keys, and the reason is the same for both
+ * vendors that build a `ScrapeResult` this way. A REGO-FIX collet family is
+ * mixed-unit — `D1_mm` on its metric rows and `D1_in` on its inch ones — and a
+ * MariTool CSV mixes three holder styles, so which spec keys a part publishes is
+ * a function of its style. Keying off row one drops whichever came second.
+ *
+ * It lived in both adapters, byte for byte, until 2026-08-29. Building the
+ * header of a {@link ScrapeResult} is this module's business rather than any
+ * manufacturer's — the same call `pause` and `conventions.CAD_COLUMN` already
+ * got, and the one `tests/vendor-boundary.test.ts` now makes automatically.
+ */
+export function unionHeader(rows) {
+    const header = [];
+    for (const row of rows) {
+        for (const key of Object.keys(row)) {
+            if (!header.includes(key))
+                header.push(key);
+        }
+    }
+    return header;
+}
 /**
  * Milliseconds between requests, wherever a scrape or a mirror loops.
  *

package/dist/vendors/destinytool/records.d.ts

@@ -94,6 +94,13 @@ export declare function shoulderDiameter(description: string, dc: number): numbe
  * column when populated, or a fallback keyed on flute count when it is not
  * (blank on 423 of 3,898 rows, 2026-08-19).
  *
+ * **The two answers are labelled, not blended.** A populated cell is
+ * `vendor-stated` and the flute-count fallback is `derived`, so a consumer that
+ * will not route a cut off this package's arithmetic can filter on the source
+ * rather than having to know which rows Destiny Tool left blank. Neither is
+ * ever `null`: the fallback covers every blank cell, so this vendor always has
+ * an answer.
+ *
  * The fallback is not a new rule invented for this vendor — it is the split
  * cutting-data presets are routed by downstream (≤3 flutes non-ferrous, >3
  * ferrous), applied here to the material-groups facet instead. Real vendor
@@ -109,10 +116,13 @@ export declare function shoulderDiameter(description: string, dc: number): numbe
  * array and a tool's own list from another has no way to notice the two
  * disagree.
  */
-export declare function materialGroups(row: ScrapedRow, flutes: number): string[];
+export declare function materialGroups(row: ScrapedRow, flutes: number): Pick<ToolRecord, 'materialGroups' | 'materialGroupsSource'>;
 /**
- * A solid end mill, always in inches — Destiny Tool publishes no metric line
- * (the `unit` fact on the family).
+ * A solid end mill, in the family's declared unit.
+ *
+ * Which is inches on the one family there is — Destiny Tool publishes no metric
+ * line — but read from the `unit` fact rather than hardcoded, so the fact stays
+ * the single authored copy the way it is for every other vendor here.
  */
 export declare function endmillRecord(row: ScrapedRow, family: BoundFamily, columns: ColumnMap, options?: MapperOptions): ToolRecord;
 export declare const RECORD_MAPPERS: RecordMappers;

package/dist/vendors/destinytool/records.js

@@ -23,7 +23,8 @@
  * row.
  */
 import { VendorResponseError } from '../../errors.js';
-import { familyBrand } from '../../family.js';
+import { fractionValue } from '../../measure.js';
+import { fact, familyBrand } from '../../family.js';
 import { BRANDS } from '../../identity.js';
 import { ISO_MATERIAL_GROUPS, toolRecord, } from '../../records.js';
 import { consoleWarn } from '../../scrape.js';
@@ -86,31 +87,18 @@ export function parseFractionInches(text) {
     const s = text.trim().replace(/"+$/, '');
     if (!s)
         throw new RangeError(`empty dimension: ${JSON.stringify(text)}`);
-    const value = s.includes('.')
-        ? Number(s)
-        : s.includes('-')
-            ? mixed(s)
-            : s.includes('/')
-                ? fraction(s)
-                : Number(s);
-    if (!Number.isFinite(value)) {
+    // The trailing quote is the only thing Destiny Tool puts around a dimension
+    // that `measure.fractionValue` does not read; the grammar itself is the one
+    // every vendor here publishes, and it is read in one place.
+    const value = fractionValue(s);
+    if (value === null) {
         throw new RangeError(`unrecognized dimension: ${JSON.stringify(text)}`);
     }
     return value;
 }
-/** `1-1/2` — a whole number and a simple fraction. */
-function mixed(s) {
-    const cut = s.indexOf('-');
-    return Number(s.slice(0, cut)) + fraction(s.slice(cut + 1));
-}
-/** `3/4`. */
-function fraction(s) {
-    const [num, den] = s.split('/');
-    return Number(num) / Number(den);
-}
 /** A dimension the kind requires, parsed as an inch fraction. */
-function required(row, columns, canonical, what) {
-    const column = columns.column(canonical, 'inches');
+function required(row, columns, canonical, unit, what) {
+    const column = columns.column(canonical, unit);
     const raw = column === null ? undefined : row[column];
     if (raw === undefined || raw.trim() === '') {
         throw new VendorResponseError(what, `no value for ${canonical} in column ${JSON.stringify(column)}`);
@@ -190,6 +178,13 @@ export function shoulderDiameter(description, dc) {
  * column when populated, or a fallback keyed on flute count when it is not
  * (blank on 423 of 3,898 rows, 2026-08-19).
  *
+ * **The two answers are labelled, not blended.** A populated cell is
+ * `vendor-stated` and the flute-count fallback is `derived`, so a consumer that
+ * will not route a cut off this package's arithmetic can filter on the source
+ * rather than having to know which rows Destiny Tool left blank. Neither is
+ * ever `null`: the fallback covers every blank cell, so this vendor always has
+ * an answer.
+ *
  * The fallback is not a new rule invented for this vendor — it is the split
  * cutting-data presets are routed by downstream (≤3 flutes non-ferrous, >3
  * ferrous), applied here to the material-groups facet instead. Real vendor
@@ -209,23 +204,31 @@ export function materialGroups(row, flutes) {
     const cell = row['isoMaterialGroups'] ?? '';
     if (cell.trim()) {
         const present = new Set(cell.split(/\s+/).filter(Boolean));
-        return ISO_MATERIAL_GROUPS.filter((group) => present.has(group));
+        return {
+            materialGroups: ISO_MATERIAL_GROUPS.filter((group) => present.has(group)),
+            materialGroupsSource: 'vendor-stated',
+        };
     }
-    if (flutes <= NON_FERROUS_MAX_FLUTES)
-        return ['N'];
-    return ['P', 'M', 'K', 'S', 'H'];
+    return {
+        materialGroups: flutes <= NON_FERROUS_MAX_FLUTES ? ['N'] : ['P', 'M', 'K', 'S', 'H'],
+        materialGroupsSource: 'derived',
+    };
 }
 /**
- * A solid end mill, always in inches — Destiny Tool publishes no metric line
- * (the `unit` fact on the family).
+ * A solid end mill, in the family's declared unit.
+ *
+ * Which is inches on the one family there is — Destiny Tool publishes no metric
+ * line — but read from the `unit` fact rather than hardcoded, so the fact stays
+ * the single authored copy the way it is for every other vendor here.
  */
 export function endmillRecord(row, family, columns, options = {}) {
+    const unit = fact(family, 'unit', family.unit);
     const what = row[ITEM_NUMBER] ?? '';
     const description = row['description'] ?? '';
-    const dc = required(row, columns, 'DC', what);
-    const fluteLength = required(row, columns, 'LCF', what);
-    const oal = required(row, columns, 'OAL', what);
-    const radColumn = columns.column('RE', 'inches');
+    const dc = required(row, columns, 'DC', unit, what);
+    const fluteLength = required(row, columns, 'LCF', unit, what);
+    const oal = required(row, columns, 'OAL', unit, what);
+    const radColumn = columns.column('RE', unit);
     const radRaw = radColumn === null ? undefined : row[radColumn];
     const radCell = radRaw && radRaw.trim() ? parseFractionInches(radRaw) : null;
     // Refused rather than allowed through as NaN: `materialGroups` reads it, and
@@ -237,17 +240,26 @@ export function endmillRecord(row, family, columns, options = {}) {
         throw new VendorResponseError(what, `no integer in column "flutes"`);
     }
     return toolRecord({
+        brand: familyBrand(family),
         vendor: BRANDS[familyBrand(family)].vendor,
         materialNumber: what,
         catalogNumber: what,
         description,
         kind: 'endmill',
-        unit: 'inches',
-        substrate: (row['material'] || (family.bmc ?? '')).toLowerCase(),
-        // No carbide grade is published; the coating id fills GRADE instead.
-        grade: row['coatingId'] ?? '',
-        materialGroups: materialGroups(row, flutes),
-        coolantThrough: family.coolantThrough ?? false,
+        unit,
+        // `series` is the vendor's own product-line name and the one column here
+        // that names one — `Viper`, `Raptor`, `DiamondBack`, and `viper-mini` and
+        // `python` in the vendor's own lower case, which stays exactly as
+        // published for the reason `records.ToolRecord.productLine` gives. It has
+        // been scraped since the adapter was written and read by nothing until
+        // now; the description cannot stand in for it, because Raptor calls itself
+        // `DVH` there and DiamondBack calls itself `DBACK RGHR`.
+        productLine: row['series']?.trim() || null,
+        substrate: (row['material'] || fact(family, 'bmc', family.bmc)).toLowerCase(),
+        // No carbide grade is published; the coating id is what there is.
+        coating: row['coatingId'] ?? '',
+        ...materialGroups(row, flutes),
+        coolantThrough: fact(family, 'coolantThrough', family.coolantThrough),
         geometry: {
             DC: dc,
             RE: cornerRadius(description, row['endStyle'] ?? '', what, dc, radCell, 

package/dist/vendors/emuge/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * EMUGE-FRANKEN — end mills, twist drills and taps, from a SAP Commerce API.
+ *
+ * Not a catalog to parse: the storefront renders its listings in the browser,
+ * so the "scrape" is a JSON client against the same unauthenticated API the
+ * site's own Vue front end reads. See `scrape.ts` for the three calls it takes
+ * and why, `value.ts` for the grammar of a vendor value string, and
+ * `records.ts` for what the vendor states that no other vendor here does — a
+ * point angle per drill, an ISO 513 rating per part — and the one thing it
+ * states nowhere at all, which is a tap's flute count.
+ *
+ * `value.ts` is pure and holds the parsing risk; `scrape.ts` is the only module
+ * that reads through a `Fetcher`.
+ */
+export * from './records.js';
+export * from './scrape.js';
+export * from './value.js';

package/dist/vendors/emuge/index.js

@@ -0,0 +1,17 @@
+/**
+ * EMUGE-FRANKEN — end mills, twist drills and taps, from a SAP Commerce API.
+ *
+ * Not a catalog to parse: the storefront renders its listings in the browser,
+ * so the "scrape" is a JSON client against the same unauthenticated API the
+ * site's own Vue front end reads. See `scrape.ts` for the three calls it takes
+ * and why, `value.ts` for the grammar of a vendor value string, and
+ * `records.ts` for what the vendor states that no other vendor here does — a
+ * point angle per drill, an ISO 513 rating per part — and the one thing it
+ * states nowhere at all, which is a tap's flute count.
+ *
+ * `value.ts` is pure and holds the parsing risk; `scrape.ts` is the only module
+ * that reads through a `Fetcher`.
+ */
+export * from './records.js';
+export * from './scrape.js';
+export * from './value.js';

package/dist/vendors/emuge/records.d.ts

@@ -0,0 +1,230 @@
+/**
+ * EMUGE-FRANKEN rows -> {@link ToolRecord}.
+ *
+ * The CSV a scrape writes holds the vendor's own value strings — `1 1/2 "`,
+ * `3 mm`, `140 deg`, `4` — rather than parsed numbers, because the file is the
+ * receipt and EMUGE's fractional inches and stated units are part of what it
+ * published. So this module is where a cell becomes a number, through
+ * `value.ts`. The closest precedent is Harvey Tool's, not Kennametal's, whose
+ * columns are already decimals.
+ *
+ * ## What EMUGE publishes that nobody else here does
+ *
+ * - **Both identity columns.** The 18-digit SAP material number and the catalog
+ *   article code, per part, so there is no `conventions.IDENTITY_DEVIATIONS`
+ *   entry — the first vendor since Kennametal that needs none.
+ * - **A point angle, per drill.** Kennametal's drill families assume theirs; the
+ *   detail record states it, so `SIG` is a mapped column here and no fact. On
+ *   all but one part: 2,669 of 2,670 drill variants state one, and part
+ *   `000000000010727800` publishes a single classification feature and no
+ *   dimensional properties at all — so its row carries no `SIG` **key**, not
+ *   an empty one. That is why `records.RECORD_GEOMETRY.drill` lists `SIG`
+ *   under `sometimes`, and why {@link angle} reads the row rather than `cell`.
+ * - **A per-part ISO 513 index.** `applicationMaterials` returns the vendor's
+ *   own P/M/K/N/S/H rating for each part, which fills `materialGroups` as
+ *   `vendor-stated`.
+ * - **A description for every part.** The grouped product's `productListInfo`
+ *   is one sentence of the vendor's own prose per product line, so every kind
+ *   here fills `description` from `conventions.DESCRIPTION_COLUMN` — including
+ *   the tap, where Kennametal has to fall back to the thread designation
+ *   because it publishes no such text. EMUGE's designation is on the CSV as
+ *   `dimensionFeatureValue` and its thread is on the record as `TP`.
+ *
+ * ## What it does not publish
+ *
+ * **No flute count on a drill or a tap.** Not on the grouped product, the
+ * variant listing, the per-part detail or any facet. A drill's comes from the
+ * family's `flutes` fact — all seventeen drill groups state
+ * `Specification: Twist drill` — and a tap's is simply absent, which is why
+ * `records.RECORD_GEOMETRY.tap` lists `NOF` under `sometimes`. EMUGE's own tap
+ * families run 2, 3 and 4 flutes across a size range, so no per-family constant
+ * could be true of every row, and 0 is not a substitute for a number nobody
+ * stated.
+ *
+ * **No CAD a scrape can reach.** The STEP, DXF and DIN 4000 documents are
+ * published behind a login — `anonymousAccess: false`, with both URL fields
+ * null — so neither `conventions.CAD_COLUMN` nor `CAD_DXF_COLUMN` is written.
+ * See `docs/EMUGE_FRANKEN_COMMERCE_API.md`.
+ */
+import { type BoundFamily, type RecordMappers } from '../../family.js';
+import { type ColumnMap, type ToolRecord } from '../../records.js';
+import { type MapperOptions, type ScrapedRow } from '../../scrape.js';
+/** The cutting-material property, spelled the same way in all three categories. */
+export declare const SUBSTRATE_COLUMN = "Cutting material";
+/**
+ * The coating property, which is **not** spelled the same way.
+ *
+ * `coating` on a milling part and `Coating` on a drill or a tap, in the same
+ * API, on the same day. Both are read and the first non-empty one wins, because
+ * relabelling one onto the other in the CSV would be this adapter deciding what
+ * the vendor meant — see `scrape.ts`.
+ */
+export declare const COATING_COLUMNS: readonly ["coating", "Coating"];
+/**
+ * Whether a part is through-coolant, by the vendor's own word for it.
+ *
+ * Three columns and three vocabularies, one per category, each a closed facet
+ * this package read off the vendor's own index on 2026-09-01 — so a value
+ * absent from here is a vocabulary that changed rather than a part that is
+ * odd, and {@link coolantThrough} refuses it by naming the table to add to.
+ *
+ * ## The facet does not cover the whole of milling
+ *
+ * The values below account for 6,862 milling variants, 2,670 drilling and
+ * 11,566 tapping. Drilling and tapping are the whole category — the same two
+ * numbers `docs/EMUGE_FRANKEN_COMMERCE_API.md` §4 gives — and milling is
+ * **159 short** of `FF01`'s 7,021, which is also `families/emuge.ts`'s two row
+ * counts added up. So 159 milling variants carry no `internal coolant supply`
+ * value at all.
+ *
+ * That is a gap in the vendor's index rather than a vocabulary that moved, and
+ * it is why {@link coolantThrough} separates the two cases: an unrecognised
+ * *value* still refuses, and a column nobody filled warns and records `false`.
+ * They were one case until 2026-09-01, and because `registry.toRecords` maps
+ * its rows, a single such part threw and took the whole family's conversion
+ * with it — 159 unindexed variants for two dead end mill CSVs.
+ */
+export declare const COOLANT_COLUMNS: Readonly<Record<string, Readonly<Record<string, boolean>>>>;
+/**
+ * The vendor's cutting materials, onto the package's own vocabulary.
+ *
+ * `FamilyFacts.bmc` names a material class — `carbide`, `hss`, `diamond` — and
+ * EMUGE's index names an alloy and a production route: HSS, HSSE and HSSE-PM
+ * are three grades of high-speed steel and all three are `hss`. `PCD` is
+ * `diamond`, which is the call `families/kennametal.ts` already made for its
+ * PCD drills: the word names the cutting material rather than the body it is
+ * brazed to.
+ *
+ * `cbn` and `ceramic` keep the vendor's own name, lowercased, because the
+ * package's three words have no counterpart for either and inventing one would
+ * be worse than recording what is standard. Closed, and it throws on anything
+ * else — the seven values below are the whole of the vendor's `HYB_AAM_MAT`
+ * facet across all three categories (2026-09-01).
+ */
+export declare const SUBSTRATES: Readonly<Record<string, string>>;
+/**
+ * The column each EMUGE-FRANKEN category states its product line in, keyed by
+ * the vendor's own category code.
+ *
+ * **One column per category, and each is a facet that partitions its category
+ * exactly.** Checked against the vendor's own index on 2026-09-01, at group
+ * level rather than by summing counts:
+ *
+ * | Category | Facet                | Values | Groups it covers | Groups in two values |
+ * | -------- | -------------------- | ------ | ---------------- | -------------------- |
+ * | `FF01`   | `AMM_PROG_LINIE`     | 15     | 554 of 554       | 2                    |
+ * | `FB01`   | `HYB_BAM_SB_GT`      | 4      | 17 of 17         | 0                    |
+ * | `FG01`   | `HYB_BAM_SB_GT`      | 17     | 414 of 414       | 0                    |
+ *
+ * That is what makes a product line here a **read and not an arbitration**.
+ * EMUGE's marketing publishes 43 overlapping product-family pages — a tap is
+ * simultaneously "Rekord B-Z Taps", "Enorm Z Taps" and "Left Hand Taps" — and
+ * choosing between those would be this package inventing a rule the vendor
+ * never stated. The facets above are the vendor's own partition of the same
+ * catalog, so there is nothing to choose.
+ *
+ * **The two milling groups that fall in two values cost nothing**, because the
+ * milling column is read per part: `H300024` and `H300025` each hold both
+ * `FRANKEN TiNox-Cut` and `FRANKEN TiNox-Cut VAR` variants, and the per-part
+ * detail record states which is which. A rule that tagged a whole group would
+ * have had to pick.
+ *
+ * **No request is added for any of this.** `Geometry` is on the grouped product
+ * and `product line` on the per-part detail, so `scrape.ts` already writes both
+ * into every row — see its three-call note.
+ */
+export declare const PRODUCT_LINE_COLUMNS: Readonly<Record<string, string>>;
+/**
+ * A category's product-line codes onto the vendor's own name for each.
+ *
+ * **Both sides are EMUGE's.** The key is the value its `HYB_BAM_SB_GT` facet
+ * publishes and the name is the title of the vendor's own product-family
+ * article page for it, read on 2026-09-01 and cited per entry. Nothing here is
+ * this package's wording, which is the whole condition on a table like this —
+ * the same rule {@link SUBSTRATES} keeps, one level less strict because that
+ * one maps onto a vocabulary this package owns and this one does not.
+ *
+ * **A category whose facet already names the line has no entry.** `FF01`'s
+ * values are `FRANKEN TOP-Cut`, `FRANKEN Hard-Cut`, `FRANKEN Alu-Cut` — the
+ * vendor's marketing names already — so milling passes through verbatim and
+ * appears nowhere below. Drilling and tapping index by a geometry code
+ * (`MULTI`, `Z`, `VA`) that matches nothing EMUGE sells under that name, which
+ * is the only reason this table exists.
+ *
+ * **A code with no article page keeps the code**, and that is a gap in the
+ * vendor's marketing rather than a hole here: `SPEED`, `FK`, `GAL`, `GG` and
+ * `TILEG` are real lines with no `/a/` page on the US storefront, so the
+ * honest answer is the vendor's own code until one appears.
+ */
+export declare const PRODUCT_LINES: Readonly<Record<string, Readonly<Record<string, string>>>>;
+/**
+ * The product line this row states, or null where the vendor states none.
+ *
+ * Three answers and they are different things. A family whose category has no
+ * entry in {@link PRODUCT_LINE_COLUMNS} is a category this adapter has not
+ * looked at, and it answers null rather than guessing at which of the row's
+ * columns is the line. A column the vendor left empty is null too — the same
+ * silence `angle` treats as an omission rather than a fault. A *value* is
+ * mapped through {@link PRODUCT_LINES} where its category has a table and
+ * passed through verbatim where it does not, which is the milling case.
+ *
+ * It does not throw on an unknown code, and that is the difference between
+ * this and `substrate`: a cutting material this package cannot map would put a
+ * wrong word in `ToolRecord.substrate`, where an unmapped product-line code is
+ * the vendor's own code and readable as one. A new EMUGE geometry showing up
+ * as `SPEED` is a name to improve, not a record to refuse.
+ */
+export declare function productLine(row: ScrapedRow, family: BoundFamily): string | null;
+/**
+ * The flute count EMUGE publishes where it has none: 64 end mill variants, on
+ * 2026-09-01. A sentinel and not a number, so it is refused rather than read.
+ */
+export declare const NO_FLUTE_COUNT = 999;
+/**
+ * A solid end mill, in the family's declared unit.
+ *
+ * The two shoulder fields fall back the way every end mill mapper here does: a
+ * family with no neck column is a plain tool whose usable length below the
+ * shank is its flute length and whose shoulder is its cutting diameter. EMUGE
+ * publishes `neck length l₃` and `neck diameter Ød₃` on the necked lines and
+ * neither on the plain ones, in the same family, so the fallback is per row
+ * rather than per family.
+ *
+ * A missing `radius r₁` is a square end and 0 is the right answer — the reason
+ * `RE` is optional on the end mill contract.
+ */
+export declare function endmillRecord(row: ScrapedRow, family: BoundFamily, columns: ColumnMap, options?: MapperOptions): ToolRecord;
+/**
+ * A twist drill, in millimetres — the only system EMUGE publishes its drill
+ * lengths in.
+ *
+ * `SIG` is a **mapped column**, which no other drill family in this package
+ * manages: the per-part detail record states the point angle outright, so
+ * nothing here is derived from a point length or assumed from a product line.
+ * It is also the one geometry key this record may not carry — one variant's
+ * cell is empty, and {@link angle} says what that costs. `NOF` is the one
+ * thing that is a fact, and `nonFerrous` with it — neither has a default
+ * anywhere, by design.
+ */
+export declare function drillRecord(row: ScrapedRow, family: BoundFamily, columns: ColumnMap, options?: MapperOptions): ToolRecord;
+/**
+ * A tap, in millimetres — including an inch-thread one.
+ *
+ * That is what the vendor published rather than a conversion this package made:
+ * a `#4-40 UNC` tap's major diameter is stated as `2.845 mm` and its shank,
+ * overall length and cutting-edge length are millimetres too. So the family
+ * declares `unit: millimeters` and there is no per-row thread system to read —
+ * the shape Kennametal needs, where one family holds both and `Thread System`
+ * is a column the scrape tags on.
+ *
+ * `DC` is **read, not derived**. Kennametal parses a major diameter out of the
+ * thread designation because its tap tables publish no diameter column; EMUGE
+ * publishes one, and reading the vendor's own number is always the better of
+ * the two. The designation is still on the CSV as `dimensionFeatureValue`, and
+ * `thread symbol` and `threads per inch` beside it.
+ *
+ * `NOF` is absent, and its absence is the vendor's silence — see the module
+ * docstring and `records.RECORD_GEOMETRY`.
+ */
+export declare function tapRecord(row: ScrapedRow, family: BoundFamily, columns: ColumnMap, options?: MapperOptions): ToolRecord;
+export declare const RECORD_MAPPERS: RecordMappers;