@factorypure/client-helpers 1.1.21 → 1.1.23

package/dist/index.d.ts

@@ -389,6 +389,8 @@ export declare const scrapeResultsSchema: z.ZodObject<{
     is_immersive: z.ZodOptional<z.ZodNull>;
     brand: z.ZodOptional<z.ZodNull>;
     company_id: z.ZodOptional<z.ZodNull>;
+    candidate_result: z.ZodOptional<z.ZodAny>;
+    confidence_override_active: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export declare const immersiveScrapeResultsSchema: z.ZodObject<{
     id: z.ZodNumber;
@@ -516,6 +518,8 @@ export declare const immersiveScrapeResultsSchema: z.ZodObject<{
     listing_hash: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     inline_link: z.ZodOptional<z.ZodNull>;
     delivery: z.ZodOptional<z.ZodNull>;
+    candidate_result: z.ZodOptional<z.ZodAny>;
+    confidence_override_active: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type ScrapeResultsType = z.infer<typeof scrapeResultsSchema>;
 export type ImmersiveScrapeResultsType = z.infer<typeof immersiveScrapeResultsSchema>;
@@ -685,6 +689,30 @@ export declare const HIDE_OVERRIDE_REASONS: {
 };
 export declare const TOO_CHEAP_MULTIPLIER = 0.75;
 export declare const TOO_EXPENSIVE_MULTIPLIER = 1.15;
+/**
+ * Rule IDs that are absolute blocks — high matching-engine confidence cannot override them.
+ * These represent explicit user intent or unambiguously bad data.
+ */
+export declare const ABSOLUTE_BLOCK_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)
+ */
+export declare function evaluateConfidenceOverride(filterResults: FilterResult[], visibilityState: VisibilityState, confidence: number, overrideThreshold?: number): 'show' | 'show_with_override' | 'hide';
 /**
  * Registry for filter rules with configuration management
  */

package/dist/index.js

@@ -280,6 +280,9 @@ export const scrapeResultsSchema = z.object({
     is_immersive: z.null().optional(),
     brand: z.null().optional(),
     company_id: z.null().optional(),
+    // Populated by matching engine helpers
+    candidate_result: z.any().optional(),
+    confidence_override_active: z.boolean().optional(),
 });
 export const immersiveScrapeResultsSchema = z.object({
     id: z.number(),
@@ -342,6 +345,9 @@ export const immersiveScrapeResultsSchema = z.object({
     listing_hash: z.string().nullable().optional(),
     inline_link: z.null().optional(),
     delivery: z.null().optional(),
+    // Populated by matching engine helpers
+    candidate_result: z.any().optional(),
+    confidence_override_active: z.boolean().optional(),
 });
 export const ResultIgnoreSchema = z.object({
     id: z.number(),
@@ -444,6 +450,60 @@ const HIDE_ALWAYS_MAP = {
 };
 export const TOO_CHEAP_MULTIPLIER = 0.75;
 export const TOO_EXPENSIVE_MULTIPLIER = 1.15;
+/**
+ * Rule IDs that are absolute blocks — high matching-engine confidence cannot override them.
+ * These represent explicit user intent or unambiguously bad data.
+ */
+export const ABSOLUTE_BLOCK_RULE_IDS = [
+    'manually_ignored',
+    'scam_source_exclusion',
+    'duplicate',
+    'high_price_outlier',
+    'low_price_outlier',
+    'skip_sku',
+];
+/**
+ * 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 const CONFIDENCE_OVERRIDABLE_RULE_IDS = [
+    'ai_comparison_mismatch',
+    'ai_sku_mismatch',
+    'calculated_sku_mismatch',
+    'search_exclusion',
+    'brand_mismatch',
+    'vendor_exclusion',
+    'competitor_exclusion',
+    'date_outlier',
+    'critical_spec_mismatch',
+];
+/**
+ * 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)
+ */
+export function evaluateConfidenceOverride(filterResults, visibilityState, confidence, overrideThreshold = 80) {
+    // Absolute blocks can never be overridden regardless of confidence
+    const hasAbsoluteBlock = filterResults.some((fr) => ABSOLUTE_BLOCK_RULE_IDS.includes(fr.ruleId));
+    if (hasAbsoluteBlock)
+        return 'hide';
+    if (visibilityState !== VisibilityState.HIDDEN)
+        return 'show';
+    // Result is hidden — check if all BLOCK-severity rules are confidence-overridable
+    const blockRules = filterResults.filter((fr) => fr.severity === FilterSeverity.BLOCK);
+    const allBlocksOverridable = blockRules.length > 0 && blockRules.every((fr) => CONFIDENCE_OVERRIDABLE_RULE_IDS.includes(fr.ruleId));
+    if (allBlocksOverridable && confidence >= overrideThreshold)
+        return 'show_with_override';
+    return 'hide';
+}
 // const wattages = Array.from({ length: 41 }, (_, i) => (5000 + i * 500).toString())
 // ===============================
 // Filter Rule Registry

package/package.json

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