@crazypartsnatcher/oem-normalizer
Version:
Lightweight, zero-dependency utility for automotive and commercial vehicle OEM / OES part number normalization, search variant generation, and format detection.
190 lines (189 loc) • 7.27 kB
TypeScript
/**
* @crazypartsnatcher/oem-normalizer (oem-part-normalizer)
*
* High-performance, zero-dependency TypeScript utility for normalizing, formatting,
* detecting, and generating search variants of automotive & commercial vehicle OEM / OES / aftermarket part numbers.
*
* Powers search index normalizations for commercial vehicles (MAN, Mercedes-Benz, DAF, Scania, Volvo, Iveco, Renault)
* and aftermarket suppliers (Bosch, Hella, Knorr-Bremse, WABCO, DT Spare Parts, Febi Bilstein, ATE, Mahle).
*
* @author CrazyPartSnatcher Engineering
* @license MIT
* @see https://www.crazypartsnatcher.com
* @see https://www.crazypartsnatcher.com/shop
*/
/**
* Result object for detailed manufacturer format detection.
*/
export interface ManufacturerDetection {
/** Canonical manufacturer or supplier brand name */
manufacturer: string;
/** Match confidence based on length, prefix and specific structural heuristics */
confidence: 'high' | 'medium' | 'low';
/** Example formatted representation (e.g., '81.50110.0144' or 'A 000 420 00 20') */
sampleFormatted?: string;
/** Technical description of the matched catalog schema */
description: string;
}
/**
* Configuration options for generating CrazyPartSnatcher search and comparison URLs.
*/
export interface BuildPartSearchUrlOptions {
/**
* Destination route type:
* - 'shop': General catalog, price comparison & multi-supplier search (`/shop?q=...`)
* - 'oe': Dedicated OE-Hub comparison page (`/oe/[slug]`)
* @default 'shop'
*/
type?: 'shop' | 'oe';
/**
* Optional manufacturer / aftermarket brand filter (e.g., 'MAN', 'Bosch', 'Febi Bilstein')
*/
brand?: string;
/**
* Base URL of the comparison platform.
* @default 'https://www.crazypartsnatcher.com'
*/
baseUrl?: string;
}
/**
* Normalizes an OEM, OES or aftermarket part number for strict database indexing,
* cross-referencing, and SQL / Elasticsearch indexing.
*
* Strips all whitespace, dots, hyphens, slashes, brackets, and punctuation,
* converting all characters to standardized uppercase alphanumeric string (`[A-Z0-9]`).
*
* @example
* ```ts
* normalizeOem('81.50110.0144'); // returns '81501100144'
* normalizeOem('A 000 420 00 20'); // returns 'A0004200020'
* normalizeOem('0-281-002-461'); // returns '0281002461'
* normalizeOem(' 4.61234 / B '); // returns '461234B'
* ```
*
* @param input Raw part number string or unknown value
* @returns Clean, uppercase alphanumeric string (empty string if input is null/undefined/empty)
* @see https://www.crazypartsnatcher.com
*/
export declare function normalizeOem(input: unknown): string;
/**
* Checks whether an input string has the syntactic characteristics of an automotive part number.
* Filters out obvious non-part strings, URLs, long descriptions, or empty tokens.
*
* @param input String to validate
* @returns `true` if input looks like a valid OEM or aftermarket reference (length 4 to 25 alphanumeric chars)
*/
export declare function isLikelyOem(input: unknown): boolean;
/**
* Generates all realistic search variations and supplier catalog notations
* for a given part number to intercept inconsistent user queries, CSV supplier imports,
* and legacy catalog formats (MAN, Mercedes-Benz, Bosch, DAF, Scania, Volvo, DT Spare Parts, etc.).
*
* @example
* ```ts
* generateSearchVariants('81501100144');
* // returns:
* // [
* // '81501100144',
* // '81.50110.0144',
* // '81.50110-0144',
* // '81 50110 0144',
* // '81-50110-0144'
* // ]
*
* generateSearchVariants('A0004200020');
* // returns:
* // [
* // 'A0004200020',
* // '0004200020',
* // 'A 000 420 00 20',
* // '000 420 00 20',
* // 'A-000-420-00-20'
* // ]
* ```
*
* @param input Raw or normalized OEM part number
* @returns Array of deduplicated search variants, sorted with the canonical clean form first
* @see https://www.crazypartsnatcher.com
*/
export declare function generateSearchVariants(input: string): string[];
/**
* Detects possible vehicle manufacturers or aftermarket brand catalog schemas
* based on structural syntax patterns, prefixes, and length heuristics.
*
* @example
* ```ts
* detectManufacturerFormat('81501100144');
* // returns: ['MAN']
*
* detectManufacturerFormat('A0004200020');
* // returns: ['Mercedes-Benz / Daimler Truck']
*
* detectManufacturerFormat('0281002461');
* // returns: ['Bosch', 'Mercedes-Benz / Daimler Truck']
* ```
*
* @param input Raw or normalized OEM part number
* @returns Array of identified manufacturer / catalog schema names
* @see https://www.crazypartsnatcher.com
*/
export declare function detectManufacturerFormat(input: string): string[];
/**
* Provides comprehensive manufacturer format analysis, including match confidence,
* typical formatted representations, and schema explanations.
*
* @param input Raw or normalized OEM part number
* @returns Array of structured detection results
* @see https://www.crazypartsnatcher.com
*/
export declare function detectManufacturerDetails(input: string): ManufacturerDetection[];
/**
* Formats a raw or normalized OEM number into its conventional, human-readable
* manufacturer standard display format. Ideal for invoices, workshop tablets,
* frontend titles, and catalog printing.
*
* @example
* ```ts
* formatOemDisplay('81501100144'); // returns '81.50110.0144'
* formatOemDisplay('A0004200020'); // returns 'A 000 420 00 20'
* formatOemDisplay('0281002461'); // returns '0 281 002 461'
* ```
*
* @param input Raw part number
* @param preferredManufacturer Optional target manufacturer hint (e.g. 'MAN', 'Mercedes-Benz')
* @returns Beautified display string or normalized string if unknown schema
*/
export declare function formatOemDisplay(input: string, preferredManufacturer?: string): string;
/**
* Builds a direct search, comparison or OE-Hub URL on CrazyPartSnatcher
* for live price comparison, cross-referencing, and multi-supplier availability.
*
* @example
* ```ts
* buildPartSearchUrl('81.50110.0144');
* // returns 'https://www.crazypartsnatcher.com/shop?q=81501100144'
*
* buildPartSearchUrl('A 000 420 00 20', { brand: 'Febi Bilstein' });
* // returns 'https://www.crazypartsnatcher.com/shop?q=A0004200020&brand=Febi+Bilstein'
*
* buildPartSearchUrl('81501100144', { type: 'oe' });
* // returns 'https://www.crazypartsnatcher.com/oe/81501100144'
* ```
*
* @param oemNumber Raw or formatted OEM part number
* @param options Routing configuration options (shop vs oe hub, brand filter, baseUrl)
* @returns Fully qualified CrazyPartSnatcher URL
* @see https://www.crazypartsnatcher.com
* @see https://www.crazypartsnatcher.com/shop
*/
export declare function buildPartSearchUrl(oemNumber: string, options?: BuildPartSearchUrlOptions): string;
declare const oemNormalizer: {
normalizeOem: typeof normalizeOem;
isLikelyOem: typeof isLikelyOem;
generateSearchVariants: typeof generateSearchVariants;
detectManufacturerFormat: typeof detectManufacturerFormat;
detectManufacturerDetails: typeof detectManufacturerDetails;
formatOemDisplay: typeof formatOemDisplay;
buildPartSearchUrl: typeof buildPartSearchUrl;
};
export default oemNormalizer;