@factorypure/client-helpers 1.2.0 → 1.2.1

package/dist/index.d.ts

@@ -257,6 +257,19 @@ export declare enum VisibilityState {
     VISIBLE_WITH_WARNINGS = "VISIBLE_WITH_WARNINGS",
     VISIBLE = "VISIBLE"
 }
+/**
+ * Result groups that replace VisibilityState with richer classification.
+ * Each result is assigned a group after all filter rules run:
+ *   MATCH           — no active blocks (shown; undercut determination is a separate downstream step)
+ *   LOW_LIKELIHOOD  — medium confidence only (50–79); shown in "needs review" if cheaper
+ *   NO_MATCH        — low confidence or has an active block rule (hidden)
+ */
+export declare enum ResultGroup {
+    MATCH = "match",
+    LOW_LIKELIHOOD = "low_likelihood",
+    NO_MATCH = "no_match",
+    EXCLUDED = "excluded"
+}
 /**
  * Structured result from a filter rule evaluation
  */
@@ -310,7 +323,7 @@ export declare const scrapeResultsSchema: z.ZodObject<{
         metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
         timestamp: z.ZodString;
     }, z.core.$strip>>>;
-    visibility_state: z.ZodOptional<z.ZodEnum<typeof VisibilityState>>;
+    visibility_state: z.ZodOptional<z.ZodEnum<typeof ResultGroup>>;
     regexUnitResults: z.ZodNullable<z.ZodObject<{
         inch: z.ZodArray<z.ZodObject<{
             value: z.ZodString;
@@ -445,7 +458,7 @@ export declare const immersiveScrapeResultsSchema: z.ZodObject<{
         metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
         timestamp: z.ZodString;
     }, z.core.$strip>>>;
-    visibility_state: z.ZodOptional<z.ZodEnum<typeof VisibilityState>>;
+    visibility_state: z.ZodOptional<z.ZodEnum<typeof ResultGroup>>;
     brand: z.ZodNullable<z.ZodString>;
     company_id: z.ZodNullable<z.ZodNumber>;
     regexUnitResults: z.ZodNullable<z.ZodObject<{
@@ -702,6 +715,8 @@ export declare const HIDE_REASONS: {
     CALCULATED_BRAND_MISMATCH: string;
     SCAM_SOURCE_EXCLUSION: string;
     AI_COMPARISON_MISMATCH: string;
+    ABSOLUTE_LOW_PRICE_OUTLIER: string;
+    ABSOLUTE_HIGH_PRICE_OUTLIER: string;
 };
 export declare const HIDE_OVERRIDE_REASONS: {
     SKU_MATCH: string;
@@ -719,23 +734,23 @@ export declare const TOO_EXPENSIVE_MULTIPLIER = 1.15;
  * These represent explicit user intent or unambiguously bad data.
  */
 export declare const ABSOLUTE_BLOCK_RULE_IDS: readonly string[];
+/**
+ * Rule IDs that represent explicit admin/security decisions.
+ * These are the ONLY blocks respected when a confidence override or match confirmation is present.
+ * Operational blocks (out_of_stock, price outliers, etc.) are superseded by overrides.
+ */
+export declare const MANUAL_EXCLUSION_RULE_IDS: readonly string[];
 /**
  * Rule IDs that can be overridden when the matching-engine confidence is high enough.
  * These represent heuristics that may be wrong when identifier/title matching is strong.
  */
 export declare const CONFIDENCE_OVERRIDABLE_RULE_IDS: readonly string[];
 /**
- * Evaluates whether a result should be surfaced given its filter state and matching confidence.
- *
- * Returns:
- *  - `'hide'`              — result must not be shown
- *  - `'show'`              — result passes all filters normally
- *  - `'show_with_override'`— result failed soft filters but confidence is high enough to surface it anyway
- *
- * @param filterResults      The filter_results array from the filter engine
- * @param visibilityState    The visibility_state computed by the filter engine
- * @param confidence         Matching-engine confidence score (0–100)
- * @param overrideThreshold  Minimum confidence to override a soft BLOCK rule (default 80)
+ * @deprecated Confidence overrides are now handled by the filter engine.
+ * Pass a `confidenceMap` to `filterScrapeResultsV2` — the engine injects a synthetic
+ * `high_confidence_override` rule result when confidence ≥ 80, which is listed in the
+ * `overridableBy` array of all soft block/warning rules. `visibility_state` on each result
+ * is then accurate and final before `getShownResults` is called.
  */
 export declare function evaluateConfidenceOverride(filterResults: FilterResult[], visibilityState: VisibilityState, confidence: number, overrideThreshold?: number): 'show' | 'show_with_override' | 'hide';
 /**
@@ -782,11 +797,18 @@ export declare class FilterEngine {
     /**
      * Evaluate rules for a batch of results
      */
-    evaluateBatch<T extends ScrapeResultsType | ImmersiveScrapeResultsType>(results: T[], variant: FilterContext<T>['variant'], variantScrapeOptions: VariantScrapeOptionsType, vendorScrapeOptions: VendorScrapeOptionsType, globalScrapeOptions: GlobalScrapeOptionsType, comparisonMap?: ComparisonMapType, matchConfirmationMap?: MatchConfirmationMapType): T[];
+    evaluateBatch<T extends ScrapeResultsType | ImmersiveScrapeResultsType>(results: T[], variant: FilterContext<T>['variant'], variantScrapeOptions: VariantScrapeOptionsType, vendorScrapeOptions: VendorScrapeOptionsType, globalScrapeOptions: GlobalScrapeOptionsType, comparisonMap?: ComparisonMapType, matchConfirmationMap?: MatchConfirmationMapType, matchResult?: MatchResult): T[];
     /**
-     * Calculate visibility state based on filter results
+     * Calculate which result group a scrape result belongs to.
+     *   MATCH           — no manual blocks, and either an override is present or no blocks at all
+     *   LOW_LIKELIHOOD  — no overrides, medium_confidence is the only block (worth reviewing if cheaper)
+     *   NO_MATCH        — manual/security block present, or no overrides and more than one active block
+     *
+     * Key rule: any override (high_confidence_override, match_confirmation_override, sku_match, etc.)
+     * supersedes ALL operational blocks (out_of_stock, price outliers, mismatch rules, etc.).
+     * Only explicit admin decisions in MANUAL_EXCLUSION_RULE_IDS can block an overridden result.
      */
-    calculateVisibility(filterResults: FilterResult[]): VisibilityState;
+    calculateGroup(filterResults: FilterResult[], resultPrice: number, variantPrice: number): ResultGroup;
 }
 /**
  * Create and populate a registry with all built-in rules
@@ -829,7 +851,7 @@ export declare function createCustomFilterRule(config: {
  * Filter scrape results using the new rule-based engine
  * This provides more flexibility and better extensibility than the legacy filterScrapeResults
  */
-export declare const filterScrapeResultsV2: <T extends ScrapeResultsType | ImmersiveScrapeResultsType>({ scrapeResults, variant, variantScrapeOptions, vendorScrapeOptions, globalScrapeOptions, filterConfig, customRules, comparisonMap, matchConfirmationMap, }: {
+export declare const filterScrapeResultsV2: <T extends ScrapeResultsType | ImmersiveScrapeResultsType>({ scrapeResults, variant, variantScrapeOptions, vendorScrapeOptions, globalScrapeOptions, filterConfig, customRules, comparisonMap, matchConfirmationMap, matchResult, }: {
     scrapeResults: T[];
     variant: {
         id: number;
@@ -847,6 +869,7 @@ export declare const filterScrapeResultsV2: <T extends ScrapeResultsType | Immer
     customRules?: FilterRule[];
     comparisonMap?: ComparisonMapType;
     matchConfirmationMap?: MatchConfirmationMapType;
+    matchResult?: MatchResult;
 }) => T[];
 export declare const filterScrapeResults: <T extends ScrapeResultsType | ImmersiveScrapeResultsType>({ scrapeResults, variant, variantScrapeOptions, vendorScrapeOptions, globalScrapeOptions, }: {
     scrapeResults: T[];
@@ -889,14 +912,24 @@ export declare function findUnitVariations(data: any): any;
  * confidence is at or above overrideThreshold.
  * Results are sorted by price ascending by default; pass sortDirection to override.
  */
-export declare function getShownResults(matchResult: MatchResult, sortedResults: (ScrapeResultsType | ImmersiveScrapeResultsType)[], minConfidence: number, sortDirection?: 'asc' | 'desc', overrideThreshold?: number): (ScrapeResultsType | ImmersiveScrapeResultsType)[];
+export declare function getShownResults(sortedResults: (ScrapeResultsType | ImmersiveScrapeResultsType)[], sortDirection?: 'asc' | 'desc'): (ScrapeResultsType | ImmersiveScrapeResultsType)[];
+/**
+ * Extracts undercut results from the MATCH group — competitors selling strictly cheaper
+ * than the variant price (price < variantPrice).
+ *
+ * This is the downstream step that divides getShownResults output into two categories:
+ *   - Undercuts:      price < variantPrice  (competitors beating our price)
+ *   - Other matches:  price ≥ variantPrice  (competitors at or above our price)
+ *
+ * @param shownResults  Output of getShownResults (already filtered to MATCH group)
+ * @param variantPrice  The variant's current selling price
+ */
+export declare function getUndercutResults(shownResults: (ScrapeResultsType | ImmersiveScrapeResultsType)[], variantPrice: number): (ScrapeResultsType | ImmersiveScrapeResultsType)[];
 /**
- * Derives the needs-review results from a MatchResult.
- * Includes medium-confidence candidates (reviewConfidenceMin <= confidence < minConfidence)
- * that are cheaper than both the variant price and the cheapest shown result.
- * Also includes high-confidence candidates whose visibility_state is not VISIBLE but meet
- * the same price conditions.
+ * Derives the needs-review results from sortedResults.
+ * Returns LOW_LIKELIHOOD results (medium confidence, no other active blocks) that are
+ * cheaper than both the variant price and the cheapest shown result.
  * Results are sorted by price ascending.
  */
-export declare function getNeedsReviewResults(matchResult: MatchResult, sortedResults: (ScrapeResultsType | ImmersiveScrapeResultsType)[], shownResults: (ScrapeResultsType | ImmersiveScrapeResultsType)[], variantPrice: number, minConfidence: number, reviewConfidenceMin: number): (ScrapeResultsType | ImmersiveScrapeResultsType)[];
+export declare function getNeedsReviewResults(sortedResults: (ScrapeResultsType | ImmersiveScrapeResultsType)[], shownResults: (ScrapeResultsType | ImmersiveScrapeResultsType)[], variantPrice: number): (ScrapeResultsType | ImmersiveScrapeResultsType)[];
 export {};

package/dist/index.js

@@ -217,6 +217,20 @@ export var VisibilityState;
     VisibilityState["VISIBLE_WITH_WARNINGS"] = "VISIBLE_WITH_WARNINGS";
     VisibilityState["VISIBLE"] = "VISIBLE";
 })(VisibilityState || (VisibilityState = {}));
+/**
+ * Result groups that replace VisibilityState with richer classification.
+ * Each result is assigned a group after all filter rules run:
+ *   MATCH           — no active blocks (shown; undercut determination is a separate downstream step)
+ *   LOW_LIKELIHOOD  — medium confidence only (50–79); shown in "needs review" if cheaper
+ *   NO_MATCH        — low confidence or has an active block rule (hidden)
+ */
+export var ResultGroup;
+(function (ResultGroup) {
+    ResultGroup["MATCH"] = "match";
+    ResultGroup["LOW_LIKELIHOOD"] = "low_likelihood";
+    ResultGroup["NO_MATCH"] = "no_match";
+    ResultGroup["EXCLUDED"] = "excluded";
+})(ResultGroup || (ResultGroup = {}));
 /**
  * Structured result from a filter rule evaluation
  */
@@ -264,7 +278,7 @@ export const scrapeResultsSchema = z.object({
     hide_override_reasons: z.array(z.string()),
     // New filter system fields
     filter_results: z.array(filterResultSchema).optional(),
-    visibility_state: z.nativeEnum(VisibilityState).optional(),
+    visibility_state: z.nativeEnum(ResultGroup).optional(),
     regexUnitResults: z.nullable(regexUnitResultsSchema),
     // add these properties as null to make ts play nice with the ImmersiveScrapeResultsType union
     google_product_link: z.null().optional(),
@@ -335,7 +349,7 @@ export const immersiveScrapeResultsSchema = z.object({
     hide_override_reasons: z.array(z.string()),
     // New filter system fields
     filter_results: z.array(filterResultSchema).optional(),
-    visibility_state: z.nativeEnum(VisibilityState).optional(),
+    visibility_state: z.nativeEnum(ResultGroup).optional(),
     brand: z.string().nullable(),
     company_id: z.number().nullable(),
     regexUnitResults: z.nullable(regexUnitResultsSchema),
@@ -439,6 +453,8 @@ export const HIDE_REASONS = {
     CALCULATED_BRAND_MISMATCH: 'Calculated Brand Mismatch',
     SCAM_SOURCE_EXCLUSION: 'Scam Source Exclusion',
     AI_COMPARISON_MISMATCH: 'AI Comparison Mismatch',
+    ABSOLUTE_LOW_PRICE_OUTLIER: 'Extreme Price Outlier',
+    ABSOLUTE_HIGH_PRICE_OUTLIER: 'Extreme High Price',
 };
 export const HIDE_OVERRIDE_REASONS = {
     SKU_MATCH: 'SKU Match',
@@ -467,6 +483,8 @@ const HIDE_ALWAYS_MAP = {
     [HIDE_REASONS.VENDOR_EXCLUSION]: false,
     [HIDE_REASONS.SCAM_SOURCE_EXCLUSION]: true,
     [HIDE_REASONS.AI_COMPARISON_MISMATCH]: false,
+    [HIDE_REASONS.ABSOLUTE_LOW_PRICE_OUTLIER]: true,
+    [HIDE_REASONS.ABSOLUTE_HIGH_PRICE_OUTLIER]: true,
 };
 export const TOO_CHEAP_MULTIPLIER = 0.75;
 export const TOO_EXPENSIVE_MULTIPLIER = 1.15;
@@ -476,10 +494,27 @@ export const TOO_EXPENSIVE_MULTIPLIER = 1.15;
  */
 export const ABSOLUTE_BLOCK_RULE_IDS = [
     'manually_ignored',
+    'manually_excluded',
+    'out_of_stock',
     'scam_source_exclusion',
     'duplicate',
     'high_price_outlier',
     'low_price_outlier',
+    'absolute_low_price_outlier',
+    'absolute_high_price_outlier',
+];
+/**
+ * Rule IDs that represent explicit admin/security decisions.
+ * These are the ONLY blocks respected when a confidence override or match confirmation is present.
+ * Operational blocks (out_of_stock, price outliers, etc.) are superseded by overrides.
+ */
+export const MANUAL_EXCLUSION_RULE_IDS = [
+    'manually_ignored',
+    'manually_excluded',
+    'scam_source_exclusion',
+    'duplicate',
+    'absolute_low_price_outlier',
+    'absolute_high_price_outlier',
 ];
 /**
  * Rule IDs that can be overridden when the matching-engine confidence is high enough.
@@ -498,17 +533,11 @@ export const CONFIDENCE_OVERRIDABLE_RULE_IDS = [
     'skip_sku',
 ];
 /**
- * Evaluates whether a result should be surfaced given its filter state and matching confidence.
- *
- * Returns:
- *  - `'hide'`              — result must not be shown
- *  - `'show'`              — result passes all filters normally
- *  - `'show_with_override'`— result failed soft filters but confidence is high enough to surface it anyway
- *
- * @param filterResults      The filter_results array from the filter engine
- * @param visibilityState    The visibility_state computed by the filter engine
- * @param confidence         Matching-engine confidence score (0–100)
- * @param overrideThreshold  Minimum confidence to override a soft BLOCK rule (default 80)
+ * @deprecated Confidence overrides are now handled by the filter engine.
+ * Pass a `confidenceMap` to `filterScrapeResultsV2` — the engine injects a synthetic
+ * `high_confidence_override` rule result when confidence ≥ 80, which is listed in the
+ * `overridableBy` array of all soft block/warning rules. `visibility_state` on each result
+ * is then accurate and final before `getShownResults` is called.
  */
 export function evaluateConfidenceOverride(filterResults, visibilityState, confidence, overrideThreshold = 80) {
     // Absolute blocks can never be overridden regardless of confidence
@@ -610,7 +639,21 @@ export class FilterEngine {
     /**
      * Evaluate rules for a batch of results
      */
-    evaluateBatch(results, variant, variantScrapeOptions, vendorScrapeOptions, globalScrapeOptions, comparisonMap, matchConfirmationMap) {
+    evaluateBatch(results, variant, variantScrapeOptions, vendorScrapeOptions, globalScrapeOptions, comparisonMap, matchConfirmationMap, matchResult) {
+        // Build a map of result id → best matching candidate so we can look up confidence
+        // and attach candidate_result to each filtered result.
+        const candidateMap = new Map();
+        for (const c of matchResult?.candidates ?? []) {
+            candidateMap.set(c.candidateId.toString(), c);
+        }
+        for (const c of matchResult?.insufficientDataCandidates ?? []) {
+            if (!candidateMap.has(c.candidateId.toString()))
+                candidateMap.set(c.candidateId.toString(), c);
+        }
+        for (const c of matchResult?.nonMatchCandidates ?? []) {
+            if (!candidateMap.has(c.candidateId.toString()))
+                candidateMap.set(c.candidateId.toString(), c);
+        }
         return results.map((result) => {
             const context = {
                 result,
@@ -624,11 +667,66 @@ export class FilterEngine {
             const filterResults = this.evaluateResult(context);
             // Merge with existing filter_results from batch processing (duplicates, search exclusions, etc.)
             const existingFilterResults = result.filter_results || [];
-            const allFilterResults = [...existingFilterResults, ...filterResults];
-            const visibilityState = this.calculateVisibility(allFilterResults);
+            let allFilterResults = [...existingFilterResults, ...filterResults];
+            // Look up the matching-engine candidate for this result and attach it so downstream
+            // consumers have access to match metadata (confidence, scores, reasons, etc.).
+            const candidate = candidateMap.get(result.id.toString());
+            if (candidate)
+                result.candidate_result = candidate;
+            const confidence = candidate?.confidence;
+            // Inject a confidence-tier filter_result so calculateVisibility is the single source
+            // of truth for visibility — no confidence gate is needed in getShownResults:
+            //   ≥ 80  → high_confidence_override (INFO, isOverride: true) — cancels soft blocks
+            //           listed in each rule's overridableBy (e.g. ai_comparison_mismatch)
+            //   50–79 → medium_confidence (BLOCK) — hidden; overridable by match_confirmation_override
+            //   < 50 or not evaluated → low_confidence (BLOCK) — hidden; overridable by match_confirmation_override
+            if (confidence !== undefined && confidence >= 80) {
+                allFilterResults = [
+                    ...allFilterResults,
+                    {
+                        ruleId: 'high_confidence_override',
+                        severity: FilterSeverity.INFO,
+                        message: 'High Confidence Match',
+                        metadata: { isOverride: true, confidence },
+                        timestamp: new Date().toISOString(),
+                    },
+                ];
+            }
+            else if (confidence !== undefined && confidence >= 50) {
+                allFilterResults = [
+                    ...allFilterResults,
+                    {
+                        ruleId: 'medium_confidence',
+                        severity: FilterSeverity.BLOCK,
+                        message: 'Medium Confidence Match',
+                        metadata: { confidence },
+                        timestamp: new Date().toISOString(),
+                    },
+                ];
+            }
+            else {
+                allFilterResults = [
+                    ...allFilterResults,
+                    {
+                        ruleId: 'low_confidence',
+                        severity: FilterSeverity.BLOCK,
+                        message: 'Low Confidence Match',
+                        metadata: { confidence },
+                        timestamp: new Date().toISOString(),
+                    },
+                ];
+            }
+            const resultPrice = result.extracted_total || result.extracted_price || 0;
+            const group = this.calculateGroup(allFilterResults, resultPrice, variant.price);
+            // confidence_override_active: true when high confidence cancelled a soft block on this result
+            const hadBlocksBefore = confidence !== undefined &&
+                confidence >= 80 &&
+                allFilterResults.some((fr) => fr.severity === FilterSeverity.BLOCK && fr.ruleId !== 'high_confidence_override');
             // Populate new fields
             result.filter_results = allFilterResults;
-            result.visibility_state = visibilityState;
+            result.visibility_state = group;
+            result.confidence_override_active =
+                hadBlocksBefore && group !== ResultGroup.NO_MATCH && group !== ResultGroup.EXCLUDED ? true : undefined;
             // Maintain backward compatibility with old fields
             result.hide_reasons = allFilterResults
                 .filter((fr) => fr.severity === FilterSeverity.BLOCK || fr.severity === FilterSeverity.WARNING)
@@ -636,67 +734,41 @@ export class FilterEngine {
             result.hide_override_reasons = allFilterResults
                 .filter((fr) => fr.metadata?.isOverride)
                 .map((fr) => fr.message);
-            result.ignore_result = visibilityState === VisibilityState.HIDDEN;
+            result.ignore_result = group === ResultGroup.NO_MATCH || group === ResultGroup.EXCLUDED;
             return result;
         });
     }
     /**
-     * Calculate visibility state based on filter results
+     * Calculate which result group a scrape result belongs to.
+     *   MATCH           — no manual blocks, and either an override is present or no blocks at all
+     *   LOW_LIKELIHOOD  — no overrides, medium_confidence is the only block (worth reviewing if cheaper)
+     *   NO_MATCH        — manual/security block present, or no overrides and more than one active block
+     *
+     * Key rule: any override (high_confidence_override, match_confirmation_override, sku_match, etc.)
+     * supersedes ALL operational blocks (out_of_stock, price outliers, mismatch rules, etc.).
+     * Only explicit admin decisions in MANUAL_EXCLUSION_RULE_IDS can block an overridden result.
      */
-    calculateVisibility(filterResults) {
-        if (filterResults.length === 0) {
-            return VisibilityState.VISIBLE;
-        }
-        // Check for override results
+    calculateGroup(filterResults, resultPrice, variantPrice) {
         const overrideResults = filterResults.filter((fr) => fr.metadata?.isOverride);
         const blockResults = filterResults.filter((fr) => fr.severity === FilterSeverity.BLOCK);
-        const warningResults = filterResults.filter((fr) => fr.severity === FilterSeverity.WARNING);
-        // Block results that cannot be overridden
-        const nonOverridableBlocks = blockResults.filter((br) => {
-            const rule = this.registry.getRule(br.ruleId);
-            if (!rule || !rule.canBeOverridden)
-                return true;
-            // Check if any override can override this block
-            const canBeOverridden = overrideResults.some((or) => {
-                const overrideRule = this.registry.getRule(or.ruleId);
-                return overrideRule && rule.overridableBy.includes(overrideRule.id);
-            });
-            return !canBeOverridden;
-        });
-        if (nonOverridableBlocks.length > 0) {
-            return VisibilityState.HIDDEN;
-        }
-        // Check for overridable blocks
-        const overridableBlocks = blockResults.filter((br) => {
-            const rule = this.registry.getRule(br.ruleId);
-            if (!rule || !rule.canBeOverridden)
-                return false;
-            const canBeOverridden = overrideResults.some((or) => {
-                const overrideRule = this.registry.getRule(or.ruleId);
-                return overrideRule && rule.overridableBy.includes(overrideRule.id);
-            });
-            return !canBeOverridden; // Still blocked if no override present
-        });
-        if (overridableBlocks.length > 0) {
-            return VisibilityState.HIDDEN;
-        }
-        // Check for warnings that haven't been overridden
-        const nonOverriddenWarnings = warningResults.filter((wr) => {
-            const rule = this.registry.getRule(wr.ruleId);
-            if (!rule || !rule.canBeOverridden)
-                return true;
-            // Check if any override can override this warning
-            const canBeOverridden = overrideResults.some((or) => {
-                const overrideRule = this.registry.getRule(or.ruleId);
-                return overrideRule && rule.overridableBy.includes(overrideRule.id);
-            });
-            return !canBeOverridden; // Still a warning if no override present
-        });
-        // If we have non-overridden warnings, show with warnings
-        if (nonOverriddenWarnings.length > 0) {
-            return VisibilityState.VISIBLE_WITH_WARNINGS;
+        // Manual and security exclusions are always respected, regardless of confidence or overrides.
+        const hasManualBlock = blockResults.some((br) => MANUAL_EXCLUSION_RULE_IDS.includes(br.ruleId));
+        if (hasManualBlock)
+            return ResultGroup.EXCLUDED;
+        // Any override (high_confidence_override, match_confirmation_override, sku_match, etc.)
+        // supersedes all remaining operational blocks — high-confidence / confirmed results always show.
+        if (overrideResults.length > 0) {
+            return ResultGroup.MATCH;
+        }
+        // No overrides present — with nothing to cancel them, all remaining blocks are active.
+        if (blockResults.length === 0) {
+            return ResultGroup.MATCH;
         }
-        return VisibilityState.VISIBLE;
+        // Medium confidence is the only block → low likelihood (worth reviewing if cheaper)
+        if (blockResults.length === 1 && blockResults[0].ruleId === 'medium_confidence') {
+            return ResultGroup.LOW_LIKELIHOOD;
+        }
+        return ResultGroup.NO_MATCH;
     }
 }
 // ===============================
@@ -716,7 +788,7 @@ class HighPriceOutlierRule {
     overridableBy = [];
     evaluate(context) {
         const multiplier = TOO_EXPENSIVE_MULTIPLIER;
-        const isMoreExpensive = context.result.extracted_price > context.variant.price * multiplier;
+        const isMoreExpensive = (context.result.extracted_total ?? context.result.extracted_price ?? 0) > context.variant.price * multiplier;
         if (isMoreExpensive) {
             return {
                 ruleId: this.id,
@@ -724,7 +796,7 @@ class HighPriceOutlierRule {
                 message: HIDE_REASONS.HIGH_PRICE_OUTLIER,
                 metadata: {
                     variantPrice: context.variant.price,
-                    resultPrice: context.result.extracted_price,
+                    resultPrice: context.result.extracted_total ?? context.result.extracted_price ?? 0,
                     threshold: multiplier,
                 },
                 timestamp: new Date().toISOString(),
@@ -764,6 +836,72 @@ class LowPriceOutlierRule {
         return null;
     }
 }
+/**
+ * Rule for filtering results that are below an absolute price floor (50% of variant price).
+ * This rule cannot be overridden by confidence or any override — it always results in NO_MATCH.
+ */
+class AbsoluteLowPriceOutlierRule {
+    id = 'absolute_low_price_outlier';
+    name = 'Absolute Low Price Outlier';
+    description = 'Filters results below 50% of the variant price — this floor cannot be overridden';
+    severity = FilterSeverity.BLOCK;
+    priority = 99;
+    enabled = true;
+    canBeOverridden = false;
+    overridableBy = [];
+    evaluate(context) {
+        const ABSOLUTE_CUTOFF = 0.5;
+        const resultPrice = context.result.extracted_total ?? context.result.extracted_price ?? 0;
+        const isBelowAbsoluteFloor = resultPrice > 0 && resultPrice < context.variant.price * ABSOLUTE_CUTOFF;
+        if (isBelowAbsoluteFloor) {
+            return {
+                ruleId: this.id,
+                severity: this.severity,
+                message: HIDE_REASONS.ABSOLUTE_LOW_PRICE_OUTLIER,
+                metadata: {
+                    variantPrice: context.variant.price,
+                    resultPrice,
+                    threshold: ABSOLUTE_CUTOFF,
+                },
+                timestamp: new Date().toISOString(),
+            };
+        }
+        return null;
+    }
+}
+/**
+ * Rule for filtering results above an absolute price ceiling (200% of variant price).
+ * This rule cannot be overridden by confidence or any override — it always results in NO_MATCH.
+ */
+class AbsoluteHighPriceOutlierRule {
+    id = 'absolute_high_price_outlier';
+    name = 'Absolute High Price Outlier';
+    description = 'Filters results above 200% of the variant price — this ceiling cannot be overridden';
+    severity = FilterSeverity.BLOCK;
+    priority = 99;
+    enabled = true;
+    canBeOverridden = false;
+    overridableBy = [];
+    evaluate(context) {
+        const ABSOLUTE_CUTOFF = 2.0;
+        const resultPrice = context.result.extracted_total ?? context.result.extracted_price ?? 0;
+        const isAbsoluteCeiling = resultPrice > 0 && resultPrice > context.variant.price * ABSOLUTE_CUTOFF;
+        if (isAbsoluteCeiling) {
+            return {
+                ruleId: this.id,
+                severity: this.severity,
+                message: HIDE_REASONS.ABSOLUTE_HIGH_PRICE_OUTLIER,
+                metadata: {
+                    variantPrice: context.variant.price,
+                    resultPrice,
+                    threshold: ABSOLUTE_CUTOFF,
+                },
+                timestamp: new Date().toISOString(),
+            };
+        }
+        return null;
+    }
+}
 /**
  * Rule for filtering outdated listings
  */
@@ -807,7 +945,7 @@ class CompetitorExclusionRule {
     priority = 80;
     enabled = true;
     canBeOverridden = true;
-    overridableBy = ['match_confirmation_override'];
+    overridableBy = ['match_confirmation_override', 'high_confidence_override'];
     evaluate(context) {
         const lowerSource = context.result.source.toLowerCase();
         const isExcluded = context.variantScrapeOptions.competitor_exclusions.some((exclusion) => exclusion && lowerSource === exclusion.toLowerCase());
@@ -834,7 +972,13 @@ class AIComparisonMismatchRule {
     priority = 85;
     enabled = true;
     canBeOverridden = true;
-    overridableBy = ['sku_match', 'calculated_sku_match', 'alt_sku_match', 'match_confirmation_override'];
+    overridableBy = [
+        'sku_match',
+        'calculated_sku_match',
+        'alt_sku_match',
+        'match_confirmation_override',
+        'high_confidence_override',
+    ];
     evaluate(context) {
         // Only applies to results with listing_hash (primarily immersive results)
         const result = context.result;
@@ -901,7 +1045,13 @@ class SearchExclusionRule {
     priority = 60;
     enabled = true;
     canBeOverridden = true;
-    overridableBy = ['sku_match', 'calculated_sku_match', 'alt_sku_match', 'match_confirmation_override'];
+    overridableBy = [
+        'sku_match',
+        'calculated_sku_match',
+        'alt_sku_match',
+        'match_confirmation_override',
+        'high_confidence_override',
+    ];
     evaluate(context) {
         // This is handled in batch processing due to FlexSearch requirement
         return null;
@@ -919,7 +1069,7 @@ class SkipSkuRule {
     priority = 50;
     enabled = true;
     canBeOverridden = true;
-    overridableBy = ['sku_match', 'calculated_sku_match', 'alt_sku_match'];
+    overridableBy = ['sku_match', 'calculated_sku_match', 'alt_sku_match', 'high_confidence_override'];
     evaluate(context) {
         const variantSkuLower = context.variant.sku.toLowerCase();
         const allSkus = [
@@ -971,7 +1121,13 @@ class VendorExclusionRule {
     priority = 50;
     enabled = true;
     canBeOverridden = true;
-    overridableBy = ['sku_match', 'calculated_sku_match', 'alt_sku_match', 'match_confirmation_override'];
+    overridableBy = [
+        'sku_match',
+        'calculated_sku_match',
+        'alt_sku_match',
+        'match_confirmation_override',
+        'high_confidence_override',
+    ];
     //  evaluate(context: FilterContext): FilterResult | null {
     //     const nots: string[] = []
     //     const formatted = context.vendorScrapeOptions.default_skip_vendors
@@ -1102,7 +1258,13 @@ class BrandMismatchRule {
     priority = 40;
     enabled = true;
     canBeOverridden = true;
-    overridableBy = ['sku_match', 'calculated_sku_match', 'alt_sku_match', 'match_confirmation_override'];
+    overridableBy = [
+        'sku_match',
+        'calculated_sku_match',
+        'alt_sku_match',
+        'match_confirmation_override',
+        'high_confidence_override',
+    ];
     evaluate(context) {
         if (!context.result.brand) {
             return null;
@@ -1165,7 +1327,13 @@ class CalculatedSkuMismatchRule {
     priority = 30;
     enabled = true;
     canBeOverridden = true;
-    overridableBy = ['sku_match', 'calculated_sku_match', 'alt_sku_match', 'match_confirmation_override'];
+    overridableBy = [
+        'sku_match',
+        'calculated_sku_match',
+        'alt_sku_match',
+        'match_confirmation_override',
+        'high_confidence_override',
+    ];
     evaluate(context) {
         const result = context.result;
         if (!result.calculated_sku) {
@@ -1208,7 +1376,13 @@ class AISkuMismatchRule {
     priority = 30;
     enabled = true;
     canBeOverridden = true;
-    overridableBy = ['sku_match', 'calculated_sku_match', 'alt_sku_match', 'match_confirmation_override'];
+    overridableBy = [
+        'sku_match',
+        'calculated_sku_match',
+        'alt_sku_match',
+        'match_confirmation_override',
+        'high_confidence_override',
+    ];
     evaluate(context) {
         const result = context.result;
         if (!result.ai_extracted_sku) {
@@ -1251,7 +1425,13 @@ class CriticalSpecMismatchRule {
     priority = 35;
     enabled = true;
     canBeOverridden = true;
-    overridableBy = ['sku_match', 'calculated_sku_match', 'alt_sku_match', 'match_confirmation_override'];
+    overridableBy = [
+        'sku_match',
+        'calculated_sku_match',
+        'alt_sku_match',
+        'match_confirmation_override',
+        'high_confidence_override',
+    ];
     evaluate(context) {
         if (!context.result.regexUnitResults || !context.variant.regexUnitResults) {
             return null;
@@ -1529,6 +1709,45 @@ class MatchConfirmationOverrideRule {
         };
     }
 }
+class LowConfidenceRule {
+    id = 'low_confidence';
+    name = 'Low Confidence Match';
+    description = 'Result did not meet the minimum matching confidence threshold';
+    severity = FilterSeverity.BLOCK;
+    priority = 200;
+    enabled = true;
+    canBeOverridden = true;
+    overridableBy = ['match_confirmation_override'];
+    evaluate() {
+        return null; // injected synthetically by FilterEngine.evaluateBatch
+    }
+}
+class MediumConfidenceRule {
+    id = 'medium_confidence';
+    name = 'Medium Confidence Match';
+    description = 'Result meets the review confidence threshold but not the display threshold';
+    severity = FilterSeverity.BLOCK;
+    priority = 200;
+    enabled = true;
+    canBeOverridden = true;
+    overridableBy = ['match_confirmation_override'];
+    evaluate() {
+        return null; // injected synthetically by FilterEngine.evaluateBatch
+    }
+}
+class HighConfidenceOverrideRule {
+    id = 'high_confidence_override';
+    name = 'High Confidence Override';
+    description = 'Injected when matching-engine confidence meets the display threshold; cancels soft blocks via overridableBy';
+    severity = FilterSeverity.INFO;
+    priority = 200;
+    enabled = true;
+    canBeOverridden = false;
+    overridableBy = [];
+    evaluate() {
+        return null; // injected synthetically by FilterEngine.evaluateBatch
+    }
+}
 // ===============================
 // Registry Factory
 // ===============================
@@ -1540,6 +1759,8 @@ export function createDefaultFilterRegistry() {
     // Register all filter rules
     registry.registerRule(new HighPriceOutlierRule());
     registry.registerRule(new LowPriceOutlierRule());
+    registry.registerRule(new AbsoluteLowPriceOutlierRule());
+    registry.registerRule(new AbsoluteHighPriceOutlierRule());
     registry.registerRule(new DateOutlierRule());
     registry.registerRule(new CompetitorExclusionRule());
     registry.registerRule(new AIComparisonMismatchRule());
@@ -1562,6 +1783,10 @@ export function createDefaultFilterRegistry() {
     registry.registerRule(new AltSkuMatchOverrideRule());
     registry.registerRule(new ProductIdMatchOverrideRule());
     registry.registerRule(new MatchConfirmationOverrideRule());
+    // Register confidence-tier rules (injected synthetically in FilterEngine.evaluateBatch)
+    registry.registerRule(new LowConfidenceRule());
+    registry.registerRule(new MediumConfidenceRule());
+    registry.registerRule(new HighConfidenceOverrideRule());
     return registry;
 }
 /**
@@ -1653,7 +1878,7 @@ export function createCustomFilterRule(config) {
  * Filter scrape results using the new rule-based engine
  * This provides more flexibility and better extensibility than the legacy filterScrapeResults
  */
-export const filterScrapeResultsV2 = ({ scrapeResults, variant, variantScrapeOptions, vendorScrapeOptions, globalScrapeOptions, filterConfig, customRules, comparisonMap, matchConfirmationMap, }) => {
+export const filterScrapeResultsV2 = ({ scrapeResults, variant, variantScrapeOptions, vendorScrapeOptions, globalScrapeOptions, filterConfig, customRules, comparisonMap, matchConfirmationMap, matchResult, }) => {
     if (scrapeResults.length === 0 || !scrapeResults) {
         return [];
     }
@@ -1671,7 +1896,7 @@ export const filterScrapeResultsV2 = ({ scrapeResults, variant, variantScrapeOpt
     let results = handleDuplicatesV2(scrapeResults);
     results = handleSearchExclusionsV2(results, variantScrapeOptions, variant, registry);
     // Evaluate all other rules
-    results = engine.evaluateBatch(results, variant, variantScrapeOptions, vendorScrapeOptions, globalScrapeOptions, comparisonMap, matchConfirmationMap);
+    results = engine.evaluateBatch(results, variant, variantScrapeOptions, vendorScrapeOptions, globalScrapeOptions, comparisonMap, matchConfirmationMap, matchResult);
     return results;
 };
 /**
@@ -2265,67 +2490,50 @@ export function findUnitVariations(data) {
  * confidence is at or above overrideThreshold.
  * Results are sorted by price ascending by default; pass sortDirection to override.
  */
-export function getShownResults(matchResult, sortedResults, minConfidence, sortDirection = 'asc', overrideThreshold = 80) {
-    const shownResults = [];
-    matchResult.candidates.forEach((candidate) => {
-        const foundResult = sortedResults.find((res) => res.id.toString() === candidate.candidateId.toString());
-        if (candidate.confidence >= minConfidence) {
-            if (!foundResult)
-                return;
-            foundResult.candidate_result = candidate;
-            const decision = evaluateConfidenceOverride(foundResult.filter_results ?? [], foundResult.visibility_state ?? VisibilityState.VISIBLE, candidate.confidence, overrideThreshold);
-            if (decision === 'hide')
-                return;
-            if (decision === 'show_with_override') {
-                foundResult.confidence_override_active = true;
-            }
-            shownResults.push(foundResult);
-        }
-        else if (foundResult &&
-            foundResult.filter_results?.some((fr) => fr?.metadata?.isOverride === true)
-        // foundResult.filter_results?.map((fr: FilterResult) => fr.ruleId).includes('match_confirmation_override')
-        ) {
-            shownResults.push(foundResult);
-        }
-    });
-    shownResults.sort((a, b) => {
+export function getShownResults(sortedResults, sortDirection = 'asc') {
+    return [...sortedResults]
+        .filter((r) => r.visibility_state === ResultGroup.MATCH)
+        .sort((a, b) => {
         const aPrice = a.extracted_total || a.extracted_price || 0;
         const bPrice = b.extracted_total || b.extracted_price || 0;
         return sortDirection === 'asc' ? aPrice - bPrice : bPrice - aPrice;
     });
-    return shownResults.filter((r) => r.source !== 'FactoryPure');
 }
 /**
- * Derives the needs-review results from a MatchResult.
- * Includes medium-confidence candidates (reviewConfidenceMin <= confidence < minConfidence)
- * that are cheaper than both the variant price and the cheapest shown result.
- * Also includes high-confidence candidates whose visibility_state is not VISIBLE but meet
- * the same price conditions.
+ * Extracts undercut results from the MATCH group — competitors selling strictly cheaper
+ * than the variant price (price < variantPrice).
+ *
+ * This is the downstream step that divides getShownResults output into two categories:
+ *   - Undercuts:      price < variantPrice  (competitors beating our price)
+ *   - Other matches:  price ≥ variantPrice  (competitors at or above our price)
+ *
+ * @param shownResults  Output of getShownResults (already filtered to MATCH group)
+ * @param variantPrice  The variant's current selling price
+ */
+export function getUndercutResults(shownResults, variantPrice) {
+    return shownResults.filter((r) => {
+        const price = r.extracted_total || r.extracted_price || 0;
+        const isOutOfStock = r.filter_results?.some((fr) => fr.ruleId === 'out_of_stock');
+        return price > 0 && r.source !== 'FactoryPure' && price <= variantPrice && !isOutOfStock;
+    });
+}
+/**
+ * Derives the needs-review results from sortedResults.
+ * Returns LOW_LIKELIHOOD results (medium confidence, no other active blocks) that are
+ * cheaper than both the variant price and the cheapest shown result.
  * Results are sorted by price ascending.
  */
-export function getNeedsReviewResults(matchResult, sortedResults, shownResults, variantPrice, minConfidence, reviewConfidenceMin) {
+export function getNeedsReviewResults(sortedResults, shownResults, variantPrice) {
     const firstValidResult = shownResults[0];
     const cheapestShownPrice = firstValidResult?.extracted_total ?? firstValidResult?.extracted_price ?? Infinity;
-    const needsReviewResults = [];
-    matchResult.candidates.forEach((candidate) => {
-        if (candidate.confidence >= reviewConfidenceMin && candidate.confidence < minConfidence) {
-            const foundResult = sortedResults.find((res) => res.id.toString() === candidate.candidateId.toString());
-            if (!foundResult)
-                return;
-            const hasAbsoluteBlock = (foundResult.filter_results ?? []).some((fr) => ABSOLUTE_BLOCK_RULE_IDS.includes(fr.ruleId));
-            if (hasAbsoluteBlock)
-                return;
-            const priceTotal = foundResult.extracted_total || foundResult.extracted_price || 0;
-            if (priceTotal < variantPrice && priceTotal < cheapestShownPrice) {
-                foundResult.candidate_result = candidate;
-                needsReviewResults.push(foundResult);
-            }
-        }
-    });
-    needsReviewResults.sort((a, b) => {
-        const aPrice = a.extracted_total || a.extracted_price || 0;
-        const bPrice = b.extracted_total || b.extracted_price || 0;
-        return aPrice - bPrice;
-    });
-    return needsReviewResults.filter((r) => r.source !== 'FactoryPure');
+    return sortedResults
+        .filter((r) => {
+        if (r.visibility_state !== ResultGroup.LOW_LIKELIHOOD)
+            return false;
+        if (r.source === 'FactoryPure')
+            return false;
+        const price = r.extracted_total || r.extracted_price || 0;
+        return price > 0 && r.source !== 'FactoryPure' && price <= variantPrice && price <= cheapestShownPrice;
+    })
+        .sort((a, b) => (a.extracted_total || a.extracted_price || 0) - (b.extracted_total || b.extracted_price || 0));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@factorypure/client-helpers",
-    "version": "1.2.0",
+    "version": "1.2.1",
     "description": "",
     "main": "./dist/index.js",
     "types": "./dist/index.d.ts",