@toolpath/tool-scraper 0.1.0 → 2.1.0

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

@@ -0,0 +1,119 @@
+/**
+ * A family page's own title, for every brand on Kennametal's AEM platform.
+ *
+ * `scrape.ts` reads the variant *table* that a family page renders; this reads
+ * the heading above it. They are two requests against the same family because
+ * they are two different AEM resources — the table is a component node's
+ * `.variants.<code>.html` selector and the title is the page — and the second
+ * is what nothing else in this package publishes:
+ *
+ * ```html
+ * <h1>KenCut™ FF • HPFT • Square End • 6 Flutes • Plain Shank • Inch</h1>
+ * ```
+ *
+ * ## The slug does not matter
+ *
+ * The vendor's own links are `fam.<slug>.<code>.html`, and AEM resolves the
+ * page off the numeric code alone — `fam.x.100003783.html` answers 200 with
+ * exactly the page above. That is what makes this reachable from a
+ * `familyCode` and nothing else: `families/kennametal.ts` records the code
+ * because the variants endpoint needs it, and no family in it carries a slug.
+ *
+ * **`fam.<code>.html` — the code with no slug segment at all — 301s**, so the
+ * placeholder is load-bearing rather than decoration. {@link FAMILY_SLUG} is
+ * what fills it.
+ *
+ * ## Why the page is trusted to be the right one
+ *
+ * A URL built from a code that no longer names a family would answer *some*
+ * page, and a title read off it would be silently wrong for a whole table. So
+ * the page's own `data-product-code` is checked against the code that was
+ * asked for, and a mismatch throws. It is the same argument
+ * `scrape.parseVariantTable` makes for telling the vendor's no-results notice
+ * apart from a response that changed shape: a scrape that reports the wrong
+ * answer confidently is worse than one that stops.
+ *
+ * ## What the title is, and what only part of it is
+ *
+ * The whole `h1` is the family's name and reaches the CSV whole, under
+ * `conventions.FAMILY_TITLE_COLUMN`. Its **leading `•` segment** is the
+ * product line — `KenCut™ FF`, `HARVI™ I TE`, `VariMill™ Chip Splitters` —
+ * and that is the part `records.ToolRecord.productLine` keeps. Everything
+ * after it describes the shape, the flute count, the shank and the unit, which
+ * are already canonical geometry on the record.
+ *
+ * The split is the vendor's own punctuation and not a guess at where a name
+ * ends: every family title on both hosts is `•`-separated, and a title with no
+ * separator is its own product line.
+ */
+import type { Fetcher } from '../../fetch.js';
+import { type AemBrandName } from '../../identity.js';
+/**
+ * The URL shape of a family page.
+ *
+ * `{host}` and `{code}` are filled; `{slug}` is {@link FAMILY_SLUG}. Stated as
+ * one template beside `scrape.BASE` so that the two URLs this adapter builds
+ * are readable together.
+ */
+export declare const FAMILY_PAGE = "https://www.{host}/us/en/products/fam.{slug}.{code}.html";
+/**
+ * What goes where the vendor writes a human-readable slug.
+ *
+ * AEM ignores it — see the module note — and this package has no slug to put
+ * there, because a `familyCode` is the only handle `families/kennametal.ts`
+ * records. A word rather than a single letter so that a request showing up in
+ * somebody's log says what it is.
+ */
+export declare const FAMILY_SLUG = "family";
+/** The vendor's own separator between the parts of a family title. */
+export declare const TITLE_SEPARATOR = "\u2022";
+/** One family page's URL. */
+export declare function familyPageUrl(code: string, brand?: AemBrandName): string;
+/** What {@link parseFamilyPage} reads off a family page. */
+export interface FamilyPage {
+    /** The `h1`, collapsed. */
+    readonly title: string;
+    /** The code the page states for itself, or null where it states none. */
+    readonly code: string | null;
+}
+/**
+ * The family title and the page's own code.
+ *
+ * `htmlparser2` rather than a regex for the same reason `scrape.TableParser`
+ * uses it: these pages carry `&deg;`, `&Oslash;` and `&trade;` in their text,
+ * and a `KenCut&trade; FF` reaching the CSV as eleven characters is the bug
+ * `decodeEntities` exists to prevent. The `™` in every title above is exactly
+ * that entity.
+ *
+ * The **first** `h1` is taken. The pages carry one, and reading the first is
+ * what makes a second one added below the fold somebody else's problem rather
+ * than a title that changes under a re-scrape.
+ */
+export declare function parseFamilyPage(html: string): FamilyPage;
+/**
+ * A family title's leading segment — the product line.
+ *
+ * `''` in and `''` out, which is the one case the caller has to keep: a page
+ * with no `h1` states no line, and {@link fetchFamily} answers null for it
+ * rather than an empty name. See `records.ToolRecord.productLine`.
+ */
+export declare function productLineOf(title: string): string;
+/** A family's title and product line, or nulls where the page states none. */
+export interface Family {
+    readonly title: string;
+    readonly productLine: string | null;
+}
+/**
+ * One family page, read.
+ *
+ * The one network call in this module — the seam a test replaces, exactly as
+ * `scrape.fetchVariants` is.
+ *
+ * A page that answers with no `h1` is **not** an error: it is a family the
+ * vendor publishes without a heading, and the table below it is still a table
+ * of real parts. It comes back with an empty title and a null line, and the
+ * rows are written without either column rather than the scrape stopping. A
+ * page whose `data-product-code` names a *different* family is the other case
+ * and throws — see the module note.
+ */
+export declare function fetchFamily(fetcher: Fetcher, code: string, brand?: AemBrandName): Promise<Family>;

package/dist/vendors/kennametal/family.js

@@ -0,0 +1,155 @@
+/**
+ * A family page's own title, for every brand on Kennametal's AEM platform.
+ *
+ * `scrape.ts` reads the variant *table* that a family page renders; this reads
+ * the heading above it. They are two requests against the same family because
+ * they are two different AEM resources — the table is a component node's
+ * `.variants.<code>.html` selector and the title is the page — and the second
+ * is what nothing else in this package publishes:
+ *
+ * ```html
+ * <h1>KenCut™ FF • HPFT • Square End • 6 Flutes • Plain Shank • Inch</h1>
+ * ```
+ *
+ * ## The slug does not matter
+ *
+ * The vendor's own links are `fam.<slug>.<code>.html`, and AEM resolves the
+ * page off the numeric code alone — `fam.x.100003783.html` answers 200 with
+ * exactly the page above. That is what makes this reachable from a
+ * `familyCode` and nothing else: `families/kennametal.ts` records the code
+ * because the variants endpoint needs it, and no family in it carries a slug.
+ *
+ * **`fam.<code>.html` — the code with no slug segment at all — 301s**, so the
+ * placeholder is load-bearing rather than decoration. {@link FAMILY_SLUG} is
+ * what fills it.
+ *
+ * ## Why the page is trusted to be the right one
+ *
+ * A URL built from a code that no longer names a family would answer *some*
+ * page, and a title read off it would be silently wrong for a whole table. So
+ * the page's own `data-product-code` is checked against the code that was
+ * asked for, and a mismatch throws. It is the same argument
+ * `scrape.parseVariantTable` makes for telling the vendor's no-results notice
+ * apart from a response that changed shape: a scrape that reports the wrong
+ * answer confidently is worse than one that stops.
+ *
+ * ## What the title is, and what only part of it is
+ *
+ * The whole `h1` is the family's name and reaches the CSV whole, under
+ * `conventions.FAMILY_TITLE_COLUMN`. Its **leading `•` segment** is the
+ * product line — `KenCut™ FF`, `HARVI™ I TE`, `VariMill™ Chip Splitters` —
+ * and that is the part `records.ToolRecord.productLine` keeps. Everything
+ * after it describes the shape, the flute count, the shank and the unit, which
+ * are already canonical geometry on the record.
+ *
+ * The split is the vendor's own punctuation and not a guess at where a name
+ * ends: every family title on both hosts is `•`-separated, and a title with no
+ * separator is its own product line.
+ */
+import { Parser } from 'htmlparser2';
+import { VendorResponseError } from '../../errors.js';
+import { BRANDS } from '../../identity.js';
+/**
+ * The URL shape of a family page.
+ *
+ * `{host}` and `{code}` are filled; `{slug}` is {@link FAMILY_SLUG}. Stated as
+ * one template beside `scrape.BASE` so that the two URLs this adapter builds
+ * are readable together.
+ */
+export const FAMILY_PAGE = 'https://www.{host}/us/en/products/fam.{slug}.{code}.html';
+/**
+ * What goes where the vendor writes a human-readable slug.
+ *
+ * AEM ignores it — see the module note — and this package has no slug to put
+ * there, because a `familyCode` is the only handle `families/kennametal.ts`
+ * records. A word rather than a single letter so that a request showing up in
+ * somebody's log says what it is.
+ */
+export const FAMILY_SLUG = 'family';
+/** The vendor's own separator between the parts of a family title. */
+export const TITLE_SEPARATOR = '•';
+/** The attribute a family page states its own code in. */
+const PRODUCT_CODE_ATTR = 'data-product-code';
+/** One family page's URL. */
+export function familyPageUrl(code, brand = 'kennametal') {
+    const { host } = BRANDS[brand];
+    return FAMILY_PAGE.replace('{host}', host).replace('{slug}', FAMILY_SLUG).replace('{code}', code);
+}
+/**
+ * The family title and the page's own code.
+ *
+ * `htmlparser2` rather than a regex for the same reason `scrape.TableParser`
+ * uses it: these pages carry `&deg;`, `&Oslash;` and `&trade;` in their text,
+ * and a `KenCut&trade; FF` reaching the CSV as eleven characters is the bug
+ * `decodeEntities` exists to prevent. The `™` in every title above is exactly
+ * that entity.
+ *
+ * The **first** `h1` is taken. The pages carry one, and reading the first is
+ * what makes a second one added below the fold somebody else's problem rather
+ * than a title that changes under a re-scrape.
+ */
+export function parseFamilyPage(html) {
+    let title = null;
+    let depth = 0;
+    let text = '';
+    let code = null;
+    const parser = new Parser({
+        onopentag: (tag, attribs) => {
+            if (tag === 'h1' && title === null)
+                depth += 1;
+            const stated = attribs[PRODUCT_CODE_ATTR];
+            if (code === null && stated !== undefined && stated !== '')
+                code = stated;
+        },
+        ontext: (chunk) => {
+            if (depth > 0)
+                text += chunk;
+        },
+        onclosetag: (tag) => {
+            if (tag === 'h1' && depth > 0) {
+                depth -= 1;
+                if (depth === 0) {
+                    title = text.split(/\s+/).filter(Boolean).join(' ');
+                    text = '';
+                }
+            }
+        },
+    }, { decodeEntities: true });
+    parser.write(html);
+    parser.end();
+    return { title: title ?? '', code };
+}
+/**
+ * A family title's leading segment — the product line.
+ *
+ * `''` in and `''` out, which is the one case the caller has to keep: a page
+ * with no `h1` states no line, and {@link fetchFamily} answers null for it
+ * rather than an empty name. See `records.ToolRecord.productLine`.
+ */
+export function productLineOf(title) {
+    return (title.split(TITLE_SEPARATOR)[0] ?? '').trim();
+}
+/**
+ * One family page, read.
+ *
+ * The one network call in this module — the seam a test replaces, exactly as
+ * `scrape.fetchVariants` is.
+ *
+ * A page that answers with no `h1` is **not** an error: it is a family the
+ * vendor publishes without a heading, and the table below it is still a table
+ * of real parts. It comes back with an empty title and a null line, and the
+ * rows are written without either column rather than the scrape stopping. A
+ * page whose `data-product-code` names a *different* family is the other case
+ * and throws — see the module note.
+ */
+export async function fetchFamily(fetcher, code, brand = 'kennametal') {
+    const url = familyPageUrl(code, brand);
+    const { title, code: stated } = parseFamilyPage(await fetcher.text(url));
+    if (stated !== null && stated !== code) {
+        throw new VendorResponseError(url, `is the page for ${JSON.stringify(stated)} and not ${JSON.stringify(code)} — ` +
+            `the family code was retired or redirected, and its title would name the ` +
+            `wrong product line for every row of the table`);
+    }
+    const line = productLineOf(title);
+    return { title, productLine: line === '' ? null : line };
+}

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

@@ -15,6 +15,7 @@
  * code here at all.
  */
 export * from './cad.js';
+export * from './family.js';
 export * from './materials.js';
 export * from './records.js';
 export * from './scrape.js';

package/dist/vendors/kennametal/index.js

@@ -15,6 +15,7 @@
  * code here at all.
  */
 export * from './cad.js';
+export * from './family.js';
 export * from './materials.js';
 export * from './records.js';
 export * from './scrape.js';

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

@@ -15,10 +15,11 @@
  *   Number` are Kennametal's header text — the labels
  *   `conventions.IDENTITY_COLUMNS` took as the convention because this vendor
  *   was first, and which Destiny Tool then did not follow.
- * - **Which column is the grade.** A drill and an end mill carry a carbide
- *   `Grade`; a tap has no carbide grade and carries `Coating`, the surface
- *   treatment, in the record's `grade` field. That is Kennametal's table
- *   shape, not a rule about taps everywhere.
+ * - **Which column is the coating.** `Coating` on every table that publishes
+ *   one, which is every tap table and some of the others. The carbide `Grade`
+ *   a drill and an end mill table also carry reaches no record: it is what the
+ *   tool is made of in Kennametal's own vocabulary, nothing downstream reads
+ *   it, and `substrate` already carries the cutting material as a fact.
  * - **That a tap's unit system is per row.** `Thread System` is a constant tag
  *   column this package appends at scrape time, and a metric and an inch tap
  *   can sit in one family — so a tap's `unit` is read per row where a drill's
@@ -43,6 +44,30 @@ import type { ScrapedRow } from '../../scrape.js';
  */
 export declare const MATERIAL_NUMBER = "Material Number";
 export declare const CATALOG_NUMBER = "ISO Catalog Number";
+/**
+ * The surface-treatment column, on the tables that publish one.
+ *
+ * Every tap table does; a drill or an end mill table may not, which is why the
+ * mappers read it with a `?? ''` rather than through a required column — an
+ * absent coating column is a table that states no coating, not a scrape fault.
+ */
+export declare const COATING = "Coating";
+/**
+ * The column {@link productLine} reads, and the one this adapter names rather
+ * than the vendor.
+ *
+ * `conventions.FAMILY_TITLE_COLUMN` is vendor-neutral because a second vendor
+ * publishing a family title should write the same column; this one is not,
+ * because it holds a *segment* of that title that this adapter chose to split
+ * out. A vendor whose product line arrives some other way has no business
+ * writing here — EMUGE reads its own `product line` and `Geometry` columns and
+ * never sees this one.
+ *
+ * Both columns are written by `scrape.scrapeFamily` under `familyTitle`, and
+ * a CSV scraped before that option existed has neither — which is why
+ * {@link productLine} reads it as absent rather than required.
+ */
+export declare const PRODUCT_LINE_COLUMN = "Product Line";
 /**
  * A drill, in the family's native unit system per its `unit` fact.
  *

package/dist/vendors/kennametal/records.js

@@ -15,10 +15,11 @@
  *   Number` are Kennametal's header text — the labels
  *   `conventions.IDENTITY_COLUMNS` took as the convention because this vendor
  *   was first, and which Destiny Tool then did not follow.
- * - **Which column is the grade.** A drill and an end mill carry a carbide
- *   `Grade`; a tap has no carbide grade and carries `Coating`, the surface
- *   treatment, in the record's `grade` field. That is Kennametal's table
- *   shape, not a rule about taps everywhere.
+ * - **Which column is the coating.** `Coating` on every table that publishes
+ *   one, which is every tap table and some of the others. The carbide `Grade`
+ *   a drill and an end mill table also carry reaches no record: it is what the
+ *   tool is made of in Kennametal's own vocabulary, nothing downstream reads
+ *   it, and `substrate` already carries the cutting material as a fact.
  * - **That a tap's unit system is per row.** `Thread System` is a constant tag
  *   column this package appends at scrape time, and a metric and an inch tap
  *   can sit in one family — so a tap's `unit` is read per row where a drill's
@@ -34,10 +35,10 @@
  * nose, `LB` and `assemblyGaugeLength` being `OAL` on a bare tool, and every
  * cutting preset. Those are true of a tool, not of a table.
  */
-import { ScraperConfigError, VendorResponseError } from '../../errors.js';
-import { familyBrand } from '../../family.js';
+import { VendorResponseError } from '../../errors.js';
+import { fact, familyBrand } from '../../family.js';
 import { BRANDS } from '../../identity.js';
-import { toolRecord } from '../../records.js';
+import { toolRecord, UNSPECIFIED, } from '../../records.js';
 import { threadMajorDiameter } from '../../thread.js';
 import { MATERIALS_COLUMN, materialClasses } from './materials.js';
 /**
@@ -46,6 +47,43 @@ import { MATERIALS_COLUMN, materialClasses } from './materials.js';
  */
 export const MATERIAL_NUMBER = 'Material Number';
 export const CATALOG_NUMBER = 'ISO Catalog Number';
+/**
+ * The surface-treatment column, on the tables that publish one.
+ *
+ * Every tap table does; a drill or an end mill table may not, which is why the
+ * mappers read it with a `?? ''` rather than through a required column — an
+ * absent coating column is a table that states no coating, not a scrape fault.
+ */
+export const COATING = 'Coating';
+/**
+ * The column {@link productLine} reads, and the one this adapter names rather
+ * than the vendor.
+ *
+ * `conventions.FAMILY_TITLE_COLUMN` is vendor-neutral because a second vendor
+ * publishing a family title should write the same column; this one is not,
+ * because it holds a *segment* of that title that this adapter chose to split
+ * out. A vendor whose product line arrives some other way has no business
+ * writing here — EMUGE reads its own `product line` and `Geometry` columns and
+ * never sees this one.
+ *
+ * Both columns are written by `scrape.scrapeFamily` under `familyTitle`, and
+ * a CSV scraped before that option existed has neither — which is why
+ * {@link productLine} reads it as absent rather than required.
+ */
+export const PRODUCT_LINE_COLUMN = 'Product Line';
+/**
+ * The vendor's own product line for this row, or null where the CSV has none.
+ *
+ * **An absent column is not a fault.** It is a table scraped without
+ * `scrape.FamilyOptions.familyTitle`, or a family page the vendor publishes
+ * with no heading, and both are rows that are otherwise complete. `null` is
+ * the answer `records.ToolRecord.productLine` defines for exactly this — see
+ * its docstring on why that is not `''`.
+ */
+function productLine(row) {
+    const stated = (row[PRODUCT_LINE_COLUMN] ?? '').trim();
+    return stated === '' ? null : stated;
+}
 /**
  * One canonical dimension, or null when this family maps or publishes none.
  *
@@ -79,12 +117,30 @@ function require_(row, columns, canonical, unit, what) {
     }
     return value;
 }
-/** A per-family constant a mapper cannot proceed without. */
-function fact(family, key, value) {
-    if (value === undefined) {
-        throw new ScraperConfigError(family.id, `a ${family.kind} family must state ${key} as a fact`);
-    }
-    return value;
+/**
+ * The workpiece-material groups, and how they were arrived at.
+ *
+ * **The distinction the column cannot make on its own is present versus
+ * blank.** The material groups are not scraped with the variant table: they
+ * come from a second CLI step (`toolpath-scrape materials`) that sweeps the
+ * `workpieceMaterialDetail` facet and writes {@link MATERIALS_COLUMN} into the
+ * CSV. A family that step never ran over has **no such column**, and
+ * `node/csv.parseCsv` fills `''` only for cells under a column that is in the
+ * header — so the cell is `undefined` on an unswept CSV and `''` on a swept
+ * one whose part the vendor rates for nothing.
+ *
+ * Those are different claims and the record now keeps them apart: an
+ * `unspecified` label says this package has no evidence, `[]` says the vendor's
+ * own index has none. All
+ * 129 taps land on the second after a sweep — Kennametal indexes no tap by
+ * workpiece material at all — and reading that as "unconstrained" would put
+ * every tap under every material.
+ */
+function materialGroups(row) {
+    const cell = row[MATERIALS_COLUMN];
+    if (cell === undefined)
+        return { materialGroups: null, materialGroupsSource: UNSPECIFIED };
+    return { materialGroups: materialClasses(cell), materialGroupsSource: 'vendor-stated' };
 }
 /**
  * The `Thread System` tag, refusing anything that is not one of the two.
@@ -129,15 +185,20 @@ export function drillRecord(row, family, columns) {
     const unit = fact(family, 'unit', family.unit);
     const what = row[MATERIAL_NUMBER] ?? '';
     return toolRecord({
+        brand: familyBrand(family),
         vendor: BRANDS[familyBrand(family)].vendor,
         materialNumber: what,
         catalogNumber: row[CATALOG_NUMBER] ?? '',
-        description: row[CATALOG_NUMBER] ?? '',
+        productLine: productLine(row),
+        // Kennametal publishes no description column on any table. The catalog
+        // number is already on the record, and repeating it here said nothing —
+        // see `records.ToolRecord.description`.
+        description: '',
         kind: 'drill',
         unit,
         substrate: fact(family, 'bmc', family.bmc),
-        grade: row['Grade'] ?? '',
-        materialGroups: materialClasses(row[MATERIALS_COLUMN]),
+        coating: row[COATING] ?? '',
+        ...materialGroups(row),
         coolantThrough: fact(family, 'coolantThrough', family.coolantThrough),
         nonFerrous: fact(family, 'nonFerrous', family.nonFerrous),
         geometry: {
@@ -170,19 +231,22 @@ export function tapRecord(row, family, columns) {
     const tdz = row['D1-TDZ'] ?? '';
     const what = row[MATERIAL_NUMBER] ?? '';
     return toolRecord({
+        brand: familyBrand(family),
         vendor: BRANDS[familyBrand(family)].vendor,
         materialNumber: what,
         catalogNumber: row[CATALOG_NUMBER] ?? '',
-        // The designation is part of what a tap *is*, and the catalog number alone
-        // does not carry the size.
-        description: `${row[CATALOG_NUMBER] ?? ''} ${tdz}`,
+        // The one Kennametal table that publishes per-part text: the thread
+        // designation is part of what a tap *is*, and the catalog number does not
+        // carry the size. The catalog number no longer leads it — it is already on
+        // the record, and a description that restates one is not a description.
+        description: tdz,
+        productLine: productLine(row),
         kind: 'tap',
         unit,
         substrate: fact(family, 'bmc', family.bmc),
-        // A tap has no carbide grade; the record's grade carries the coating.
-        grade: row['Coating'] ?? '',
-        materialGroups: materialClasses(row[MATERIALS_COLUMN]),
-        coolantThrough: false,
+        coating: row[COATING] ?? '',
+        ...materialGroups(row),
+        coolantThrough: fact(family, 'coolantThrough', family.coolantThrough),
         geometry: {
             DC: threadMajorDiameter(tdz, system),
             TP: require_(row, columns, 'TP', unit, what),
@@ -212,15 +276,18 @@ export function endmillRecord(row, family, columns) {
     const dc = require_(row, columns, 'DC', unit, what);
     const fluteLength = require_(row, columns, 'LCF', unit, what);
     return toolRecord({
+        brand: familyBrand(family),
         vendor: BRANDS[familyBrand(family)].vendor,
         materialNumber: what,
         catalogNumber: row[CATALOG_NUMBER] ?? '',
-        description: row[CATALOG_NUMBER] ?? '',
+        // No description column here either. See the drill mapper.
+        description: '',
+        productLine: productLine(row),
         kind: 'endmill',
         unit,
         substrate: fact(family, 'bmc', family.bmc),
-        grade: row['Grade'] ?? '',
-        materialGroups: materialClasses(row[MATERIALS_COLUMN]),
+        coating: row[COATING] ?? '',
+        ...materialGroups(row),
         coolantThrough: fact(family, 'coolantThrough', family.coolantThrough),
         geometry: {
             DC: dc,

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

@@ -25,7 +25,7 @@
  */
 import type { Fetcher } from '../../fetch.js';
 import { type AemBrandName } from '../../identity.js';
-import type { ScrapeResult } from '../../scrape.js';
+import { type ScrapeResult } from '../../scrape.js';
 export declare const BASE: string;
 /**
  * The Hybris/Solr facet string that scopes a request to a family's active
@@ -101,11 +101,34 @@ export declare function parseVariantTable(html: string): VariantTable;
  * data row.
  */
 export declare function columnNames(header: readonly Cell[]): (string | null)[];
+/** What {@link scrapeFamily} accepts beyond its tags. */
+export interface FamilyOptions {
+    /**
+     * Also read the family page's own title, and tag every row with it.
+     *
+     * **Opt-in, and a second request.** The variants table states no product
+     * line — the vendor puts it in the `h1` above the table, which is a
+     * different AEM resource — so this is the one thing here that costs a
+     * request the table did not. A caller that only wants dimensions should not
+     * pay for it, and every existing caller keeps the transport it had.
+     *
+     * See `family.ts` for what the title is and which part of it becomes
+     * `records.ToolRecord.productLine`.
+     */
+    readonly familyTitle?: boolean;
+    /** Milliseconds between the two requests. Zero in tests. */
+    readonly delayMs?: number;
+}
 /**
  * Scrape one family into rows.
  *
  * `tags` is a sequence of `[name, value]` pairs appended to every row as
  * constant columns — used to tag facts the table doesn't state, e.g. the
  * thread system on a tap family.
+ *
+ * `options.familyTitle` adds two more of exactly that kind. They are tags
+ * rather than parsed columns because that is what they are: one string per
+ * family, constant down its whole table, which is the case the `tags` seam was
+ * built for.
  */
-export declare function scrapeFamily(fetcher: Fetcher, code: string, brand?: AemBrandName, tags?: readonly Tag[]): Promise<ScrapeResult>;
+export declare function scrapeFamily(fetcher: Fetcher, code: string, brand?: AemBrandName, tags?: readonly Tag[], options?: FamilyOptions): Promise<ScrapeResult>;

package/dist/vendors/kennametal/scrape.js

@@ -24,8 +24,12 @@
  * characters.
  */
 import { Parser } from 'htmlparser2';
+import { FAMILY_TITLE_COLUMN } from '../../conventions.js';
 import { VendorResponseError } from '../../errors.js';
 import { BRANDS } from '../../identity.js';
+import { pause, REQUEST_DELAY_MS } from '../../scrape.js';
+import { fetchFamily } from './family.js';
+import { PRODUCT_LINE_COLUMN } from './records.js';
 export const BASE = 'https://www.{host}/us/en/products/fam/_jcr_content/root/' +
     'responsivegrid/{node}.variants.{code}.html' +
     '?query={query}&uom=metric';
@@ -194,16 +198,37 @@ export function columnNames(header) {
  * `tags` is a sequence of `[name, value]` pairs appended to every row as
  * constant columns — used to tag facts the table doesn't state, e.g. the
  * thread system on a tap family.
+ *
+ * `options.familyTitle` adds two more of exactly that kind. They are tags
+ * rather than parsed columns because that is what they are: one string per
+ * family, constant down its whole table, which is the case the `tags` seam was
+ * built for.
  */
-export async function scrapeFamily(fetcher, code, brand = 'kennametal', tags = []) {
+export async function scrapeFamily(fetcher, code, brand = 'kennametal', tags = [], options = {}) {
     const url = variantsUrl(code, brand);
     const { header, rows: dataRows } = parseVariantTable(await fetcher.text(url));
     if (header === null) {
         throw new VendorResponseError(`family ${code}`, 'the vendor returned no variants');
     }
+    // After the table, so a family the vendor no longer publishes fails on the
+    // table it has no rows for rather than on a title nobody would have read.
+    const titled = [];
+    if (options.familyTitle === true) {
+        await pause(options.delayMs ?? REQUEST_DELAY_MS);
+        const { title, productLine } = await fetchFamily(fetcher, code, brand);
+        // A page with no heading writes no columns, rather than a column of empty
+        // strings that reads as a vendor stating an empty name. `unionHeader` is
+        // not in play here — this header is positional — so an absent tag is
+        // simply a narrower CSV.
+        if (title !== '')
+            titled.push([FAMILY_TITLE_COLUMN, title]);
+        if (productLine !== null)
+            titled.push([PRODUCT_LINE_COLUMN, productLine]);
+    }
     const names = columnNames(header);
     const kept = names.filter((name) => name !== null);
-    const csvHeader = [...kept, ...tags.map(([name]) => name)];
+    const allTags = [...tags, ...titled];
+    const csvHeader = [...kept, ...allTags.map(([name]) => name)];
     const rows = dataRows.map((row) => {
         // `dataRows` is filtered to rows exactly as long as the header, and
         // `names` has one entry per header cell, so a length mismatch here means
@@ -218,7 +243,7 @@ export async function scrapeFamily(fetcher, code, brand = 'kennametal', tags = [
             if (name !== null)
                 out[name] = row[index]?.[0] ?? '';
         });
-        for (const [name, value] of tags)
+        for (const [name, value] of allTags)
             out[name] = value;
         return out;
     });