@xapp/arachne-web-service 1.31.0 → 1.32.0

package/lib/index.d.ts

@@ -9,3 +9,4 @@ export * from "./utils/agenticProvider";
 export * from "./llm/LLMProvider";
 export type { ResourceType } from "puppeteer-core";
 export type { RequestHeaderRule } from "@xapp/arachne";
+export * from "./taxonomy/ServiceTaxonomy";

package/lib/index.js

@@ -23,4 +23,5 @@ __exportStar(require("./utils/pageAgenticSignals"), exports);
 __exportStar(require("./utils/checkMcpServer"), exports);
 __exportStar(require("./utils/agenticProvider"), exports);
 __exportStar(require("./llm/LLMProvider"), exports);
+__exportStar(require("./taxonomy/ServiceTaxonomy"), exports);
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,kCAAkC;AAClC,sDAAoC;AACpC,2CAAyB;AACzB,gDAA8B;AAC9B,8DAA4C;AAC5C,6DAA2C;AAC3C,yDAAuC;AACvC,0DAAwC;AACxC,oDAAkC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,kCAAkC;AAClC,sDAAoC;AACpC,2CAAyB;AACzB,gDAA8B;AAC9B,8DAA4C;AAC5C,6DAA2C;AAC3C,yDAAuC;AACvC,0DAAwC;AACxC,oDAAkC;AAMlC,6DAA2C"}

package/lib/taxonomy/ServiceTaxonomy.d.ts

@@ -0,0 +1,134 @@
+/**
+ * A job a homeowner asks for and a business may advertise, e.g. `plumbing.water_heater.tankless_install`.
+ */
+export interface TaxonomyJob {
+    /**
+     * Canonical slug, `trade.family.job` or `trade.job` for trades without families.  Stable once published.
+     */
+    slug: string;
+    /**
+     * A symptom or situation homeowners state that no website advertises.  The extractor never emits these.
+     */
+    homeowner_only: boolean;
+    /**
+     * Family, trade or advertised job a homeowner-only job is scored against.
+     */
+    rolls_up_to?: string;
+    /**
+     * Appears rarely, but is a capability a business either has or does not.
+     */
+    rare?: boolean;
+    /**
+     * Approximate frequency in the labeled lead samples.  Shows where demand concentrates; not a target.
+     */
+    count?: number;
+    /**
+     * Words homeowners and websites use for the job.
+     */
+    synonyms?: string[];
+    /**
+     * Slug that replaces this one.  Slugs are never renamed, only deprecated.
+     */
+    deprecated_by?: string;
+}
+export interface TaxonomyFamily {
+    slug: string;
+    /**
+     * What websites call the family, e.g. "AC repair".
+     */
+    website_terms?: string[];
+    jobs: TaxonomyJob[];
+}
+export interface TaxonomyTrade {
+    slug: string;
+    rare?: boolean;
+    families?: TaxonomyFamily[];
+    /**
+     * Jobs that sit directly under the trade.
+     */
+    jobs?: TaxonomyJob[];
+    /**
+     * Qualifiers that shape a job without being one, e.g. roofing structure type.
+     */
+    modifiers?: Record<string, string[]>;
+}
+export interface TaxonomyDefinition {
+    slug: string;
+    definition: string;
+}
+export interface Taxonomy {
+    version: string;
+    trades: TaxonomyTrade[];
+    /**
+     * Non-canonical slug to canonical slug.
+     */
+    aliases: Record<string, string>;
+    /**
+     * Slug prefix to canonical prefix, for trades folded into another.
+     */
+    alias_prefixes: Record<string, string>;
+    /**
+     * Tri-state business flags.
+     */
+    capability_flags: TaxonomyDefinition[];
+    /**
+     * Business attributes that are lists of values.
+     */
+    capability_lists: TaxonomyDefinition[];
+    certifications: string[];
+    equipment_types: string[];
+    specialty_materials: string[];
+    gear: string[];
+    sub_trades: string[];
+    /**
+     * What the homeowner side captures about a request.
+     */
+    qualifiers: Record<string, string[]>;
+}
+/**
+ * A job with the trade and family it sits in.
+ */
+export interface TaxonomyJobEntry extends TaxonomyJob {
+    trade: string;
+    /**
+     * Undefined when the job sits directly under the trade.
+     */
+    family?: string;
+}
+/**
+ * Service Taxonomy v1, the vocabulary shared by website extraction and homeowner lead labeling.
+ */
+export declare const SERVICE_TAXONOMY_V1: Taxonomy;
+/**
+ * Lookups over a taxonomy: canonical slugs, aliases and the family a job is scored in.
+ */
+export declare class ServiceTaxonomy {
+    private readonly taxonomy;
+    readonly version: string;
+    readonly jobs: TaxonomyJobEntry[];
+    private readonly bySlug;
+    private readonly families;
+    private readonly trades;
+    constructor(taxonomy?: Taxonomy);
+    job(slug: string): TaxonomyJobEntry | undefined;
+    isFamily(slug: string): boolean;
+    isTrade(slug: string): boolean;
+    /**
+     * Jobs a business website can be tagged with: not homeowner-only, not deprecated.
+     *
+     * @param trades Limit to these trades
+     */
+    extractableJobs(trades?: string[]): TaxonomyJobEntry[];
+    /**
+     * Maps a slug, alias or deprecated slug to the current canonical slug.
+     *
+     * @returns The canonical slug, or undefined when the slug is not in the taxonomy
+     */
+    resolve(slug: string): string | undefined;
+    /**
+     * The family a job is scored in, or its trade when the trade has no families.
+     *
+     * @returns The family or trade slug, or undefined when the slug is not in the taxonomy
+     */
+    familyOf(slug: string): string | undefined;
+}

package/lib/taxonomy/ServiceTaxonomy.js

@@ -0,0 +1,95 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceTaxonomy = exports.SERVICE_TAXONOMY_V1 = void 0;
+/*! Copyright (c) 2026, XAPP AI */
+const v1_json_1 = __importDefault(require("./v1.json"));
+/**
+ * Service Taxonomy v1, the vocabulary shared by website extraction and homeowner lead labeling.
+ */
+exports.SERVICE_TAXONOMY_V1 = v1_json_1.default;
+/**
+ * Lookups over a taxonomy: canonical slugs, aliases and the family a job is scored in.
+ */
+class ServiceTaxonomy {
+    constructor(taxonomy = exports.SERVICE_TAXONOMY_V1) {
+        var _a, _b;
+        this.taxonomy = taxonomy;
+        this.version = taxonomy.version;
+        this.jobs = [];
+        this.families = new Set();
+        this.trades = new Set();
+        for (const trade of taxonomy.trades) {
+            this.trades.add(trade.slug);
+            for (const job of (_a = trade.jobs) !== null && _a !== void 0 ? _a : []) {
+                this.jobs.push(Object.assign(Object.assign({}, job), { trade: trade.slug }));
+            }
+            for (const family of (_b = trade.families) !== null && _b !== void 0 ? _b : []) {
+                this.families.add(family.slug);
+                for (const job of family.jobs) {
+                    this.jobs.push(Object.assign(Object.assign({}, job), { trade: trade.slug, family: family.slug }));
+                }
+            }
+        }
+        this.bySlug = new Map(this.jobs.map((job) => [job.slug, job]));
+    }
+    job(slug) {
+        return this.bySlug.get(slug);
+    }
+    isFamily(slug) {
+        return this.families.has(slug);
+    }
+    isTrade(slug) {
+        return this.trades.has(slug);
+    }
+    /**
+     * Jobs a business website can be tagged with: not homeowner-only, not deprecated.
+     *
+     * @param trades Limit to these trades
+     */
+    extractableJobs(trades) {
+        return this.jobs.filter((job) => !job.homeowner_only && !job.deprecated_by && (!trades || trades.includes(job.trade)));
+    }
+    /**
+     * Maps a slug, alias or deprecated slug to the current canonical slug.
+     *
+     * @returns The canonical slug, or undefined when the slug is not in the taxonomy
+     */
+    resolve(slug) {
+        var _a;
+        let candidate = slug === null || slug === void 0 ? void 0 : slug.trim().toLowerCase();
+        if (!candidate) {
+            return undefined;
+        }
+        candidate = (_a = this.taxonomy.aliases[candidate]) !== null && _a !== void 0 ? _a : candidate;
+        if (!this.bySlug.has(candidate)) {
+            const prefix = Object.keys(this.taxonomy.alias_prefixes).find((p) => candidate.startsWith(p));
+            if (prefix) {
+                candidate = this.taxonomy.alias_prefixes[prefix] + candidate.slice(prefix.length);
+            }
+        }
+        // Follow deprecations, guarding against a cycle
+        const seen = new Set();
+        let job = this.bySlug.get(candidate);
+        while ((job === null || job === void 0 ? void 0 : job.deprecated_by) && !seen.has(job.slug)) {
+            seen.add(job.slug);
+            job = this.bySlug.get(job.deprecated_by);
+        }
+        return job === null || job === void 0 ? void 0 : job.slug;
+    }
+    /**
+     * The family a job is scored in, or its trade when the trade has no families.
+     *
+     * @returns The family or trade slug, or undefined when the slug is not in the taxonomy
+     */
+    familyOf(slug) {
+        var _a;
+        const canonical = this.resolve(slug);
+        const job = canonical ? this.bySlug.get(canonical) : undefined;
+        return job ? (_a = job.family) !== null && _a !== void 0 ? _a : job.trade : undefined;
+    }
+}
+exports.ServiceTaxonomy = ServiceTaxonomy;
+//# sourceMappingURL=ServiceTaxonomy.js.map

package/lib/taxonomy/ServiceTaxonomy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ServiceTaxonomy.js","sourceRoot":"","sources":["../../src/taxonomy/ServiceTaxonomy.ts"],"names":[],"mappings":"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"}