@factorypure/client-helpers 1.2.0 → 1.3.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { MatchResult } from '@factorypure/matching-engine';
 import { z } from 'zod';
+export * from './repricing.js';
 /**
  * @packageDocumentation
  * @module @factorypure/client-helpers
@@ -257,6 +258,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 +324,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 +459,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 +716,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 +735,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 +798,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 +852,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 +870,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 +913,23 @@ 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 {};
+export declare function getNeedsReviewResults(sortedResults: (ScrapeResultsType | ImmersiveScrapeResultsType)[], shownResults: (ScrapeResultsType | ImmersiveScrapeResultsType)[], variantPrice: number): (ScrapeResultsType | ImmersiveScrapeResultsType)[];