@toolpath/tool-scraper 0.1.0

package/dist/vendors/destinytool/records.js

@@ -0,0 +1,266 @@
+/**
+ * Destiny Tool rows -> {@link ToolRecord}.
+ *
+ * Destiny Tool publishes exactly one identifier (`itemNumber`), no carbide
+ * grade, no structured shank column, and dimensions as fractional-inch
+ * **strings** rather than decimal columns — the closest precedent in this
+ * package is `thread.threadMajorDiameter`'s designation parsing, not any other
+ * vendor's dimension reader, all of which already publish decimals.
+ *
+ * **Three geometry fields are derived from the free-text `description` rather
+ * than a column, because no column exists for them**: a shank diameter from a
+ * "SHK" annotation, a corner radius from a "RAD" annotation when the vendor's
+ * own `rad` cell is blank, and a neck diameter from a "NECK" annotation. The
+ * latter two were found scraping the real collection 2026-08-19. All three
+ * follow the same shape: real vendor data (a populated column) wins when
+ * present, and the description is read only when the column is not — absence
+ * is a stated fact, not a gap to fill.
+ *
+ * **A per-record derivation is not a `Fact`.** These three are arithmetic over
+ * a row, so they belong in code with their evidence beside them; a fact is a
+ * per-family constant nothing in the table states, and putting one of these
+ * there would claim a whole family's provenance for a value that varies row by
+ * row.
+ */
+import { VendorResponseError } from '../../errors.js';
+import { familyBrand } from '../../family.js';
+import { BRANDS } from '../../identity.js';
+import { ISO_MATERIAL_GROUPS, toolRecord, } from '../../records.js';
+import { consoleWarn } from '../../scrape.js';
+/**
+ * Destiny Tool's one identifier. There is no second catalog number the way
+ * Kennametal publishes an ISO number alongside a material number — the item
+ * number fills both roles on a record.
+ */
+export const ITEM_NUMBER = 'itemNumber';
+/**
+ * `"1/8 SHK"`, `'1/4" SHK'` — a shank diameter, stated only when it differs
+ * from the cutting diameter (a necked or reduced-shank tool). Every value
+ * observed across the real scrape (2026-08-19, 642 of 3,898 rows) is a simple
+ * fraction, optionally quoted; {@link parseFractionInches} also handles the
+ * decimal and mixed-number forms `cutDia`/`loc`/`oal`/`rad` use, since a
+ * future SKU stating a shank that way is not implausible.
+ */
+const SHANK = /([\d.\-/"]+)\s*SHK/i;
+/**
+ * `".035-.040 RAD"` — a corner-radius *range*, read only as a fallback when
+ * the vendor's own `rad` cell is blank. See {@link cornerRadius}.
+ */
+const RAD_RANGE = /([\d.]+)-([\d.]+)\s*RAD/i;
+/**
+ * `".090 RAD"` — a single corner-radius value, same fallback role.
+ *
+ * **No word-boundary anchor before the capture group.** A boundary sits
+ * between a non-word `.` and a word digit, so `\b[\d.]+` on `.090 RAD` starts
+ * matching at the `0` and drops the leading dot — `090` parses as 90, not
+ * 0.09, and that silently produced a 90-inch corner radius the first time this
+ * ran against the real scrape (2026-08-19). The character class itself already
+ * excludes the comma and space that precede every real match, so nothing
+ * anchors the start position but the class.
+ *
+ * `(?<!-)` keeps this from matching the upper bound of a range as if it were a
+ * lone value when both patterns are tried against the same string; the caller
+ * tries {@link RAD_RANGE} first regardless, so this is a belt-and-suspenders
+ * guard rather than the thing doing the exclusion.
+ */
+const RAD_SINGLE = /(?<!-)([\d.]+)\s*RAD/i;
+/**
+ * `".074 NECK"` — a neck (shoulder) diameter, stated only on necked tools (171
+ * of 3,898 rows, 2026-08-19). Always a plain decimal in the scraped data; no
+ * fraction or mixed-number form has been observed.
+ */
+const NECK = /([\d.]+)\s*NECK/i;
+/**
+ * Flute counts at or below this route to the non-ferrous material-group
+ * fallback — see {@link materialGroups}.
+ */
+export const NON_FERROUS_MAX_FLUTES = 3;
+/**
+ * A Destiny Tool dimension string, in inches.
+ *
+ * Every form seen across the real scrape (2026-08-19): a decimal (`.093`), a
+ * bare or quoted whole number (`1`, `1"`), a simple fraction (`3/4`), or a
+ * mixed number, quoted or not (`1-1/2`, `1-1/2"`).
+ */
+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)) {
+        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');
+    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)}`);
+    }
+    return parseFractionInches(raw);
+}
+/**
+ * The shank diameter: parsed off a "SHK" annotation when the tool is necked or
+ * reduced-shank, or the cutting diameter otherwise.
+ *
+ * Destiny Tool has no structured shank column at all — unlike Kennametal,
+ * where an absent `D` column would be a scrape bug, here a shank equal to the
+ * cut diameter is simply never stated in the vendor's own text either (checked
+ * over the full scrape, 2026-08-19).
+ */
+export function shankDiameter(description, dc) {
+    const match = SHANK.exec(description);
+    return match?.[1] ? parseFractionInches(match[1]) : dc;
+}
+/**
+ * The corner radius, in priority order.
+ *
+ * 1. The vendor's own `rad` cell, when populated — real data wins, and this is
+ *    trusted outright the way every scraped column in this package is.
+ * 2. `DC / 2` on a `Ball` end mill, which Destiny Tool publishes with no
+ *    radius column at all for that style (checked 2026-08-19).
+ * 3. The description's own "RAD" annotation, for the 123 of 3,898 rows found
+ *    2026-08-19 where `endStyle` is `"Corner Radius"` but the `rad` cell is
+ *    blank and the text states one anyway. A range like `".035-.040 RAD"`
+ *    resolves to its **upper** bound: across the 370 rows that state a range
+ *    and also publish a populated `rad` cell, the cell equals the upper bound
+ *    352 times (95%) and the lower bound 18 times, so the upper bound is the
+ *    better-corroborated guess for the rows where only the range is available.
+ *
+ *    **Recovered from text, so it is checked rather than trusted outright.**
+ *    `V33220R093` states `"0.93 RAD"` where its two siblings (identical
+ *    geometry, different coating) both say `".093 RAD"` and the item number's
+ *    own `093` suffix agrees with them — a vendor typo missing a leading zero,
+ *    found running this against the real scrape. A value that would make the
+ *    tool geometrically impossible (2×RE > DC) is not used; the row falls
+ *    through to 4 instead, with a warning.
+ * 4. `0` — a real square end — when nothing states one (2 of 3,898 rows), or
+ *    when 3 recovered a value this package will not ship.
+ */
+export function cornerRadius(description, endStyle, what, dc, radCell, warn = consoleWarn) {
+    if (radCell !== null)
+        return radCell;
+    if (endStyle === 'Ball')
+        return dc / 2;
+    const range = RAD_RANGE.exec(description);
+    const single = range ? null : RAD_SINGLE.exec(description);
+    const recovered = range?.[2] ? Number(range[2]) : single?.[1] ? Number(single[1]) : null;
+    if (recovered === null)
+        return 0;
+    if (recovered * 2 > dc) {
+        warn(`  WARNING: ${what}: description states a corner radius of ` +
+            `${recovered}in, which exceeds half the ${dc}in cutting diameter — ` +
+            `likely a vendor typo; shipped as a flat end mill instead`);
+        return 0;
+    }
+    return recovered;
+}
+/**
+ * The neck (shoulder) diameter: parsed off a "NECK" annotation when the tool
+ * is necked, or the cutting diameter otherwise — a plain-shank tool below the
+ * flutes, the same convention a family with no neck column at all uses.
+ * Destiny Tool never publishes a structured neck column; the description
+ * states one on 171 of 3,898 rows (2026-08-19) and this reads it rather than
+ * defaulting every row to plain-shank.
+ */
+export function shoulderDiameter(description, dc) {
+    const match = NECK.exec(description);
+    return match?.[1] ? Number(match[1]) : dc;
+}
+/**
+ * The ISO workpiece-material groups: the vendor's own `isoMaterialGroups`
+ * 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 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
+ * data wins when present: the full scrape shows 92 ≤3-flute rows whose stated
+ * groups are not exactly `['N']` and 168 >3-flute rows whose stated groups
+ * include `N`, so this is deliberately a fallback for the blank cells and not
+ * a correction of the populated ones.
+ *
+ * **The populated cell is reordered onto `ISO_MATERIAL_GROUPS`, not passed
+ * through in Destiny Tool's own order.** Its `isoMaterialGroups` array comes
+ * back as e.g. `['M', 'P', 'S']` — alphabetical-ish, not the ISO 513 sequence
+ * every other list agrees on — and a consumer that renders a facet from one
+ * array and a tool's own list from another has no way to notice the two
+ * disagree.
+ */
+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));
+    }
+    if (flutes <= NON_FERROUS_MAX_FLUTES)
+        return ['N'];
+    return ['P', 'M', 'K', 'S', 'H'];
+}
+/**
+ * A solid end mill, always in inches — Destiny Tool publishes no metric line
+ * (the `unit` fact on the family).
+ */
+export function endmillRecord(row, family, columns, options = {}) {
+    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 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
+    // `NaN <= 3` is false, so a blank cell would silently classify the tool as
+    // ferrous P/M/K/S/H on no evidence. Kennametal's `count()` refuses the same
+    // shape for the same reason.
+    const flutes = Number.parseInt(row['flutes'] ?? '', 10);
+    if (!Number.isInteger(flutes)) {
+        throw new VendorResponseError(what, `no integer in column "flutes"`);
+    }
+    return toolRecord({
+        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,
+        geometry: {
+            DC: dc,
+            RE: cornerRadius(description, row['endStyle'] ?? '', what, dc, radCell, 
+            // `cornerRadius` owns the fallback; defaulting here too would be two
+            // layers deciding the same thing.
+            options.warn),
+            SFDM: shankDiameter(description, dc),
+            OAL: oal,
+            LCF: fluteLength,
+            'shoulder-length': fluteLength,
+            'shoulder-diameter': shoulderDiameter(description, dc),
+            NOF: flutes,
+        },
+    });
+}
+export const RECORD_MAPPERS = { endmill: endmillRecord };

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

@@ -0,0 +1,108 @@
+/**
+ * Destiny Tool's Firestore REST API -> End Mill rows.
+ *
+ * Not a page to parse: destinytool.com is a Next.js SPA built on Firebase
+ * Studio with no product data anywhere in its HTML. Every product lives in one
+ * Firestore collection, `products`, in project `studio-6030841929-4a1a2`, and
+ * the only transport is Firestore's own REST document API — unauthenticated
+ * reads against it work today (confirmed 2026-08-19):
+ *
+ * ```
+ * GET https://firestore.googleapis.com/v1/projects/{project}/databases/
+ *     (default)/documents/products
+ *     ?pageSize=300&pageToken=<token>&mask.fieldPaths=<field>&...
+ * ```
+ *
+ * `documents.list` supports no server-side filter — that needs the separate
+ * `:runQuery` structured-query endpoint instead — so this pages through the
+ * **whole** collection (4,309 documents as of 2026-08-19) and narrows to
+ * `type == 'End Mill'` after decoding. `pageToken` is opaque and
+ * random-looking; nothing about pagination here assumes an order, so a page
+ * with a token but zero documents still stops the walk rather than looping.
+ *
+ * ## Column naming, and where it differs from every other vendor here
+ *
+ * Firestore field names carry no unit suffix — `cutDia`, not `cutDia_in` — so
+ * the four dimensional fields (`cutDia`, `loc`, `oal`, `rad`) are written
+ * **with** an `_in` suffix appended here, to fit `conventions.UNIT_SUFFIX` —
+ * the rule every other family's CSV already follows (`D1_mm`/`D1_in` on a
+ * Kennametal table). There is no `_mm` half to publish — Destiny Tool states
+ * every dimension in US customary fractional inches, see the `unit` fact on
+ * `families/destinytool` — so only the `_in` column exists.
+ *
+ * **This vendor is also the one that broke the identity convention**, and the
+ * break is visible in the header this module writes: `itemNumber` where every
+ * other CSV says `Material Number`. It is recorded in
+ * `conventions.IDENTITY_DEVIATIONS` rather than corrected, because the CSV is
+ * the receipt, and relabelling a vendor's own field in it would put a lie in
+ * the file whose job is to record what the vendor published.
+ *
+ * Every other field here keeps its Firestore name verbatim — no relabelling
+ * step, because the field *is* the vendor's own label.
+ */
+import type { Fetcher } from '../../fetch.js';
+import type { ScrapeResult, ScrapedRow } from '../../scrape.js';
+export declare const PROJECT = "studio-6030841929-4a1a2";
+export declare const DOCUMENTS_URL: string;
+/**
+ * Fields pulled from the `products` collection — everything `records.ts`
+ * reads, plus `series` and `angle` for the record (unused today, but the CSV
+ * is the receipt of what the vendor published, same as REGO-FIX's unmapped
+ * `DIN_*` columns).
+ */
+export declare const FIELDS: readonly ["itemNumber", "type", "description", "series", "cutDia", "loc", "oal", "rad", "flutes", "endStyle", "angle", "material", "isoMaterialGroups", "coatingId"];
+/**
+ * The dimensional subset of {@link FIELDS} — see the module docstring for why
+ * these get an `_in` suffix and the rest do not.
+ */
+export declare const DIMENSIONAL_FIELDS: ReadonlySet<string>;
+export declare const PAGE_SIZE = 300;
+/** A decoded Firestore field value. */
+export type FirestoreValue = string | number | boolean | null | FirestoreValue[];
+/** The CSV column a Firestore field is written under. */
+export declare function columnFor(field: string): string;
+/** The CSV header this scrape writes, positional. */
+export declare const HEADER: readonly string[];
+/** The `documents.list` URL for one page. */
+export declare function pageUrl(token: string | null): string;
+/**
+ * One Firestore `Value` -> a plain value.
+ *
+ * The REST API wraps every field in a type tag (`{"stringValue": "..."}`,
+ * `{"arrayValue": {"values": [...]}}`) so that a document can be typed without
+ * a schema; nothing downstream of this function should have to know that shape.
+ */
+export declare function decodeValue(value: Record<string, unknown>): FirestoreValue;
+/** One `documents.list` entry -> its fields, decoded and flattened. */
+export declare function decodeDocument(document: {
+    fields?: Record<string, Record<string, unknown>>;
+}): Record<string, FirestoreValue>;
+/**
+ * Every document in the `products` collection, decoded, unfiltered.
+ *
+ * One request per {@link PAGE_SIZE} documents. `documents.list` returns rows in
+ * document-ID order, and Firestore auto-IDs are random, so nothing about
+ * pagination here can be an artifact of insertion order.
+ */
+export declare function fetchProducts(fetcher: Fetcher): Promise<Record<string, FirestoreValue>[]>;
+/**
+ * A decoded Firestore value as a CSV cell.
+ *
+ * `isoMaterialGroups` is the one array field here; it is written
+ * space-separated, which is the multi-value convention every vendor's CSV
+ * follows (`Material Groups` on a Kennametal table) — `records.ts` reads it
+ * back by splitting on whitespace.
+ */
+export declare function csvCell(value: FirestoreValue | undefined): string;
+/** One decoded product as a row under this scrape's own column labels. */
+export declare function toRow(product: Record<string, FirestoreValue>): ScrapedRow;
+/**
+ * Every `End Mill` row, sorted by item number.
+ *
+ * Filtering to `type == 'End Mill'` happens here rather than server-side —
+ * `documents.list` has no filter parameter — so the whole collection is
+ * fetched and narrowed after decoding. A collection with zero matching rows is
+ * refused rather than returned empty: it is the difference between "the vendor
+ * published nothing" and "this broke."
+ */
+export declare function scrapeEndMills(fetcher: Fetcher): Promise<ScrapeResult>;

package/dist/vendors/destinytool/scrape.js

@@ -0,0 +1,192 @@
+/**
+ * Destiny Tool's Firestore REST API -> End Mill rows.
+ *
+ * Not a page to parse: destinytool.com is a Next.js SPA built on Firebase
+ * Studio with no product data anywhere in its HTML. Every product lives in one
+ * Firestore collection, `products`, in project `studio-6030841929-4a1a2`, and
+ * the only transport is Firestore's own REST document API — unauthenticated
+ * reads against it work today (confirmed 2026-08-19):
+ *
+ * ```
+ * GET https://firestore.googleapis.com/v1/projects/{project}/databases/
+ *     (default)/documents/products
+ *     ?pageSize=300&pageToken=<token>&mask.fieldPaths=<field>&...
+ * ```
+ *
+ * `documents.list` supports no server-side filter — that needs the separate
+ * `:runQuery` structured-query endpoint instead — so this pages through the
+ * **whole** collection (4,309 documents as of 2026-08-19) and narrows to
+ * `type == 'End Mill'` after decoding. `pageToken` is opaque and
+ * random-looking; nothing about pagination here assumes an order, so a page
+ * with a token but zero documents still stops the walk rather than looping.
+ *
+ * ## Column naming, and where it differs from every other vendor here
+ *
+ * Firestore field names carry no unit suffix — `cutDia`, not `cutDia_in` — so
+ * the four dimensional fields (`cutDia`, `loc`, `oal`, `rad`) are written
+ * **with** an `_in` suffix appended here, to fit `conventions.UNIT_SUFFIX` —
+ * the rule every other family's CSV already follows (`D1_mm`/`D1_in` on a
+ * Kennametal table). There is no `_mm` half to publish — Destiny Tool states
+ * every dimension in US customary fractional inches, see the `unit` fact on
+ * `families/destinytool` — so only the `_in` column exists.
+ *
+ * **This vendor is also the one that broke the identity convention**, and the
+ * break is visible in the header this module writes: `itemNumber` where every
+ * other CSV says `Material Number`. It is recorded in
+ * `conventions.IDENTITY_DEVIATIONS` rather than corrected, because the CSV is
+ * the receipt, and relabelling a vendor's own field in it would put a lie in
+ * the file whose job is to record what the vendor published.
+ *
+ * Every other field here keeps its Firestore name verbatim — no relabelling
+ * step, because the field *is* the vendor's own label.
+ */
+import { VendorResponseError } from '../../errors.js';
+import { compare } from '../../order.js';
+export const PROJECT = 'studio-6030841929-4a1a2';
+export const DOCUMENTS_URL = `https://firestore.googleapis.com/v1/projects/${PROJECT}/databases/` +
+    `(default)/documents/products`;
+/**
+ * Fields pulled from the `products` collection — everything `records.ts`
+ * reads, plus `series` and `angle` for the record (unused today, but the CSV
+ * is the receipt of what the vendor published, same as REGO-FIX's unmapped
+ * `DIN_*` columns).
+ */
+export const FIELDS = [
+    'itemNumber',
+    'type',
+    'description',
+    'series',
+    'cutDia',
+    'loc',
+    'oal',
+    'rad',
+    'flutes',
+    'endStyle',
+    'angle',
+    'material',
+    'isoMaterialGroups',
+    'coatingId',
+];
+/**
+ * The dimensional subset of {@link FIELDS} — see the module docstring for why
+ * these get an `_in` suffix and the rest do not.
+ */
+export const DIMENSIONAL_FIELDS = new Set(['cutDia', 'loc', 'oal', 'rad']);
+export const PAGE_SIZE = 300;
+/** The tool type this scrape narrows to. */
+const END_MILL = 'End Mill';
+/** The CSV column a Firestore field is written under. */
+export function columnFor(field) {
+    return DIMENSIONAL_FIELDS.has(field) ? `${field}_in` : field;
+}
+/** The CSV header this scrape writes, positional. */
+export const HEADER = FIELDS.map(columnFor);
+/** The `documents.list` URL for one page. */
+export function pageUrl(token) {
+    const params = new URLSearchParams();
+    params.set('pageSize', String(PAGE_SIZE));
+    for (const field of FIELDS)
+        params.append('mask.fieldPaths', field);
+    if (token)
+        params.append('pageToken', token);
+    return `${DOCUMENTS_URL}?${params.toString()}`;
+}
+/**
+ * One Firestore `Value` -> a plain value.
+ *
+ * The REST API wraps every field in a type tag (`{"stringValue": "..."}`,
+ * `{"arrayValue": {"values": [...]}}`) so that a document can be typed without
+ * a schema; nothing downstream of this function should have to know that shape.
+ */
+export function decodeValue(value) {
+    if ('stringValue' in value)
+        return value['stringValue'];
+    if ('integerValue' in value) {
+        return Number.parseInt(value['integerValue'], 10);
+    }
+    if ('doubleValue' in value)
+        return value['doubleValue'];
+    if ('booleanValue' in value)
+        return value['booleanValue'];
+    if ('nullValue' in value)
+        return null;
+    if ('arrayValue' in value) {
+        const array = value['arrayValue'];
+        return (array.values ?? []).map(decodeValue);
+    }
+    throw new VendorResponseError(DOCUMENTS_URL, `unrecognized Firestore value shape: ${Object.keys(value).sort().join(', ')}`);
+}
+/** One `documents.list` entry -> its fields, decoded and flattened. */
+export function decodeDocument(document) {
+    const decoded = {};
+    for (const [key, value] of Object.entries(document.fields ?? {})) {
+        decoded[key] = decodeValue(value);
+    }
+    return decoded;
+}
+/**
+ * Every document in the `products` collection, decoded, unfiltered.
+ *
+ * One request per {@link PAGE_SIZE} documents. `documents.list` returns rows in
+ * document-ID order, and Firestore auto-IDs are random, so nothing about
+ * pagination here can be an artifact of insertion order.
+ */
+export async function fetchProducts(fetcher) {
+    const documents = [];
+    let token = null;
+    for (;;) {
+        const page = await fetcher.json(pageUrl(token));
+        const docs = page.documents ?? [];
+        documents.push(...docs.map(decodeDocument));
+        token = page.nextPageToken ?? null;
+        if (!token || docs.length === 0)
+            break;
+    }
+    return documents;
+}
+/**
+ * A decoded Firestore value as a CSV cell.
+ *
+ * `isoMaterialGroups` is the one array field here; it is written
+ * space-separated, which is the multi-value convention every vendor's CSV
+ * follows (`Material Groups` on a Kennametal table) — `records.ts` reads it
+ * back by splitting on whitespace.
+ */
+export function csvCell(value) {
+    if (value === undefined || value === null)
+        return '';
+    if (Array.isArray(value))
+        return value.map((v) => String(v)).join(' ');
+    return String(value);
+}
+/** One decoded product as a row under this scrape's own column labels. */
+export function toRow(product) {
+    const row = {};
+    for (const field of FIELDS)
+        row[columnFor(field)] = csvCell(product[field]);
+    return row;
+}
+/**
+ * Every `End Mill` row, sorted by item number.
+ *
+ * Filtering to `type == 'End Mill'` happens here rather than server-side —
+ * `documents.list` has no filter parameter — so the whole collection is
+ * fetched and narrowed after decoding. A collection with zero matching rows is
+ * refused rather than returned empty: it is the difference between "the vendor
+ * published nothing" and "this broke."
+ */
+export async function scrapeEndMills(fetcher) {
+    const products = await fetchProducts(fetcher);
+    const matching = products.filter((p) => p['type'] === END_MILL);
+    if (matching.length === 0) {
+        throw new VendorResponseError(DOCUMENTS_URL, `no End Mill rows among ${products.length} products — the schema or ` +
+            `the type label changed`);
+    }
+    matching.sort((a, b) => compare(String(a['itemNumber']), String(b['itemNumber'])));
+    return {
+        header: HEADER,
+        rows: matching.map(toRow),
+        source: DOCUMENTS_URL,
+        familyCode: null,
+    };
+}

package/dist/vendors/kennametal/cad.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Vendor CAD model URLs: material number in, a static STEP link out.
+ *
+ * Kennametal's product pages don't host their CAD models — a third party does
+ * (CDS Visual, on `product-config.net`), and the page reaches it in one of two
+ * ways. For an *assembly* it POSTs a job, polls a batch, and gets back a
+ * transient generated ZIP. For a **single part with no child components** —
+ * every holder in this catalog — it takes a different branch entirely and asks
+ * for a pre-built static file:
+ *
+ * ```
+ * GET https://www.product-config.net/catalog3/cad?d=kennametal&id=<material>
+ * ```
+ *
+ * That returns `staticURLs`, a map of format key -> permanent CloudFront URL,
+ * and the files behind it are ordinary objects with a `Last-Modified` in 2024.
+ * The response also states `authenticatedDownload: false`, which is what makes
+ * a direct link viable: no login, no session, no token.
+ *
+ * `docs/KENNAMETAL_CAD_API.md` documents the endpoint and the format keys.
+ * This module scrapes one of them — `stp-lwm`, the lightweight STEP, which is
+ * the collision model to give a CAM package as holder geometry.
+ *
+ * ## Why the download half is not in this module
+ *
+ * Mirroring every STEP file onto disk is a maintainer's batch job — it takes
+ * an output directory, writes ~54 KB per part with a rate-limit pause between,
+ * and has no return value a caller wants. It lives in `node/cad-mirror.ts` and
+ * is reachable only from the CLI.
+ *
+ * What a backend consuming this package wants is the permanent URL, which is
+ * what {@link lightweightStepUrl} and {@link annotateCadUrls} give it — to
+ * link to, or to fetch on demand, rather than to bulk-mirror. The seam was
+ * already here: the annotate step writes a URL precisely so that downloading
+ * is a separate, later, optional step.
+ */
+import { type Fetcher } from '../../fetch.js';
+import { type ScrapeResult } from '../../scrape.js';
+export declare const CAD_API = "https://www.product-config.net/catalog3/cad?d=kennametal&id={material}";
+/**
+ * The `staticURLs` key for the lightweight STEP — CDS calls it LWM, the vendor
+ * UI calls it "3D Anti Collision Model", and it is the simplified solid rather
+ * than the full graphical model (`stp-gtm`).
+ *
+ * The column it is written to is `conventions.CAD_COLUMN`, shared with every
+ * other vendor's scraper because a consumer reads exactly one. What is
+ * Kennametal-specific is *which* of CDS Visual's formats fills it — that is
+ * this constant, and it stays here.
+ */
+export declare const LIGHTWEIGHT_STEP = "stp-lwm";
+/** The subset of the CDS payload this module reads. */
+export interface CadPayload {
+    cadAvailable?: boolean;
+    staticURLs?: Record<string, unknown>;
+}
+/** The CAD metadata for one material number. */
+export declare function fetchCad(fetcher: Fetcher, material: string): Promise<CadPayload>;
+/**
+ * The lightweight STEP URL from a CAD payload, or null when there is none.
+ *
+ * Null is a real state and not an error: the vendor's own UI carries a "we do
+ * not have any CAD models available for download" case, and a holder without a
+ * published model is a holder this package should say nothing about rather
+ * than offer a dead link for. All twenty holders scraped so far do have one,
+ * which is exactly why the absent case needs a test rather than a reassuring
+ * assumption.
+ */
+export declare function lightweightStepUrl(payload: CadPayload): string | null;
+/** What {@link annotateCadUrls} answers with. */
+export interface CadAnnotation {
+    scrape: ScrapeResult;
+    /**
+     * How many rows got a URL — deliberately not the row count, so a run that
+     * silently found nothing reads as `0 of 12` at the call site instead of as
+     * success.
+     */
+    found: number;
+}
+/**
+ * Add (or refresh) the CAD model column on a toolholding scrape.
+ *
+ * Safe to re-run, like the thread-pitch and material-group steps: an existing
+ * column is rebuilt rather than duplicated. A row whose lookup finds no model
+ * keeps an empty cell; the row is never dropped, because the holder still
+ * exists.
+ */
+export declare function annotateCadUrls(fetcher: Fetcher, scrape: ScrapeResult, delayMs?: number): Promise<CadAnnotation>;