@factorypure/client-helpers 1.1.24 → 1.1.26

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { MatchResult } from '@factorypure/matching-engine';
 import { z } from 'zod';
 /**
  * @packageDocumentation
@@ -520,6 +521,11 @@ export declare const immersiveScrapeResultsSchema: z.ZodObject<{
     delivery: z.ZodOptional<z.ZodNull>;
     candidate_result: z.ZodOptional<z.ZodAny>;
     confidence_override_active: z.ZodOptional<z.ZodBoolean>;
+    matchConfirmations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        confirmation_source: z.ZodString;
+        confirmed_by: z.ZodNumber;
+        confirmed_at: z.ZodString;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type ScrapeResultsType = z.infer<typeof scrapeResultsSchema>;
 export type ImmersiveScrapeResultsType = z.infer<typeof immersiveScrapeResultsSchema>;
@@ -571,6 +577,12 @@ export declare const variantScrapeOptionsSchema: z.ZodObject<{
     day_window: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
 export type VariantScrapeOptionsType = z.infer<typeof variantScrapeOptionsSchema>;
+declare const matchConfirmationSchema: z.ZodObject<{
+    confirmation_source: z.ZodString;
+    confirmed_by: z.ZodNumber;
+    confirmed_at: z.ZodString;
+}, z.core.$strip>;
+export type MatchConfirmationType = z.infer<typeof matchConfirmationSchema>;
 export declare const vendorScrapeOptionsSchema: z.ZodObject<{
     vendor_skip_skus: z.ZodArray<z.ZodString>;
     default_skip_skus: z.ZodArray<z.ZodString>;
@@ -597,6 +609,14 @@ export type ComparisonMapType = Record<string, Record<string, {
     result_description: string;
     compared_at: string;
 }>>;
+/**
+ * Manual match confirmation map, keyed by variant_id → listing_hash
+ */
+export type MatchConfirmationMapType = Record<string, Record<string, {
+    confirmation_source: string;
+    confirmed_by: number;
+    confirmed_at: string;
+}>>;
 /**
  * Context provided to filter rules during evaluation
  */
@@ -615,6 +635,7 @@ export type FilterContext<T = ScrapeResultsType | ImmersiveScrapeResultsType> =
     vendorScrapeOptions: VendorScrapeOptionsType;
     globalScrapeOptions: GlobalScrapeOptionsType;
     comparisonMap?: ComparisonMapType;
+    matchConfirmationMap?: MatchConfirmationMapType;
 };
 /**
  * Base interface for filter rules
@@ -686,6 +707,7 @@ export declare const HIDE_OVERRIDE_REASONS: {
     CALCULATED_SKU_PARTIAL_MATCH: string;
     CALCULATED_ALT_SKU_MATCH: string;
     AI_COMPARISON_MATCH: string;
+    MATCH_CONFIRMATION: string;
 };
 export declare const TOO_CHEAP_MULTIPLIER = 0.75;
 export declare const TOO_EXPENSIVE_MULTIPLIER = 1.15;
@@ -757,7 +779,7 @@ 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): T[];
+    evaluateBatch<T extends ScrapeResultsType | ImmersiveScrapeResultsType>(results: T[], variant: FilterContext<T>['variant'], variantScrapeOptions: VariantScrapeOptionsType, vendorScrapeOptions: VendorScrapeOptionsType, globalScrapeOptions: GlobalScrapeOptionsType, comparisonMap?: ComparisonMapType, matchConfirmationMap?: MatchConfirmationMapType): T[];
     /**
      * Calculate visibility state based on filter results
      */
@@ -804,7 +826,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, }: {
+export declare const filterScrapeResultsV2: <T extends ScrapeResultsType | ImmersiveScrapeResultsType>({ scrapeResults, variant, variantScrapeOptions, vendorScrapeOptions, globalScrapeOptions, filterConfig, customRules, comparisonMap, matchConfirmationMap, }: {
     scrapeResults: T[];
     variant: {
         id: number;
@@ -821,6 +843,7 @@ export declare const filterScrapeResultsV2: <T extends ScrapeResultsType | Immer
     filterConfig?: FilterConfiguration;
     customRules?: FilterRule[];
     comparisonMap?: ComparisonMapType;
+    matchConfirmationMap?: MatchConfirmationMapType;
 }) => T[];
 export declare const filterScrapeResults: <T extends ScrapeResultsType | ImmersiveScrapeResultsType>({ scrapeResults, variant, variantScrapeOptions, vendorScrapeOptions, globalScrapeOptions, }: {
     scrapeResults: T[];
@@ -856,3 +879,21 @@ export declare const calculateHideOverrideReasons: (result: ScrapeResultsType |
     found_product_ids?: string[];
 }, sku_alternates: string[]) => string[];
 export declare function findUnitVariations(data: any): any;
+/**
+ * Derives the high-confidence matched results (shownResults) from a MatchResult.
+ * Includes candidates at or above minConfidence whose visibility state is not HIDDEN,
+ * plus HIDDEN candidates whose filter rules are all confidence-overridable and whose
+ * 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)[];
+/**
+ * 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.
+ * 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 {};

package/dist/index.js

@@ -3,7 +3,10 @@ import { startOfDay, subDays } from 'date-fns';
 import { Index } from 'flexsearch';
 import EnglishPreset from 'flexsearch/lang/en';
 import { z } from 'zod';
+//  GOTCHA must restart client
 //  npm install /Users/kokkoalex/Documents/GitHub/npm-packages/client-helpers
+//  npm uninstall @factorypure/client-helpers
+//  npm install @factorypure/client-helpers --latest
 /**
  * @packageDocumentation
  * @module @factorypure/client-helpers
@@ -349,6 +352,13 @@ export const immersiveScrapeResultsSchema = z.object({
     // Populated by matching engine helpers
     candidate_result: z.any().optional(),
     confidence_override_active: z.boolean().optional(),
+    matchConfirmations: z
+        .array(z.object({
+        confirmation_source: z.string(),
+        confirmed_by: z.number(),
+        confirmed_at: z.string(),
+    }))
+        .optional(),
 });
 export const ResultIgnoreSchema = z.object({
     id: z.number(),
@@ -371,6 +381,11 @@ export const variantScrapeOptionsSchema = z.object({
     result_ignore_keys: z.array(ResultIgnoreSchema).nullable(),
     day_window: z.string().nullable(),
 });
+const matchConfirmationSchema = z.object({
+    confirmation_source: z.string(),
+    confirmed_by: z.number(),
+    confirmed_at: z.string(),
+});
 export const vendorScrapeOptionsSchema = z.object({
     vendor_skip_skus: z.array(z.string()),
     default_skip_skus: z.array(z.string()),
@@ -429,6 +444,7 @@ export const HIDE_OVERRIDE_REASONS = {
     CALCULATED_SKU_PARTIAL_MATCH: 'Calculated SKU Partial Match',
     CALCULATED_ALT_SKU_MATCH: 'Calc. Alt SKU Match',
     AI_COMPARISON_MATCH: 'AI Comparison Match',
+    MATCH_CONFIRMATION: 'Match Confirmation',
 };
 const HIDE_ALWAYS_MAP = {
     [HIDE_REASONS.HIGH_PRICE_OUTLIER]: true,
@@ -592,7 +608,7 @@ export class FilterEngine {
     /**
      * Evaluate rules for a batch of results
      */
-    evaluateBatch(results, variant, variantScrapeOptions, vendorScrapeOptions, globalScrapeOptions, comparisonMap) {
+    evaluateBatch(results, variant, variantScrapeOptions, vendorScrapeOptions, globalScrapeOptions, comparisonMap, matchConfirmationMap) {
         return results.map((result) => {
             const context = {
                 result,
@@ -601,6 +617,7 @@ export class FilterEngine {
                 vendorScrapeOptions,
                 globalScrapeOptions,
                 comparisonMap,
+                matchConfirmationMap,
             };
             const filterResults = this.evaluateResult(context);
             // Merge with existing filter_results from batch processing (duplicates, search exclusions, etc.)
@@ -788,7 +805,7 @@ class CompetitorExclusionRule {
     priority = 80;
     enabled = true;
     canBeOverridden = true;
-    overridableBy = [];
+    overridableBy = ['match_confirmation_override'];
     evaluate(context) {
         const lowerSource = context.result.source.toLowerCase();
         const isExcluded = context.variantScrapeOptions.competitor_exclusions.some((exclusion) => exclusion && lowerSource === exclusion.toLowerCase());
@@ -815,7 +832,7 @@ class AIComparisonMismatchRule {
     priority = 85;
     enabled = true;
     canBeOverridden = true;
-    overridableBy = ['sku_match', 'calculated_sku_match', 'alt_sku_match'];
+    overridableBy = ['sku_match', 'calculated_sku_match', 'alt_sku_match', 'match_confirmation_override'];
     evaluate(context) {
         // Only applies to results with listing_hash (primarily immersive results)
         const result = context.result;
@@ -882,7 +899,7 @@ class SearchExclusionRule {
     priority = 60;
     enabled = true;
     canBeOverridden = true;
-    overridableBy = ['sku_match', 'calculated_sku_match', 'alt_sku_match'];
+    overridableBy = ['sku_match', 'calculated_sku_match', 'alt_sku_match', 'match_confirmation_override'];
     evaluate(context) {
         // This is handled in batch processing due to FlexSearch requirement
         return null;
@@ -946,7 +963,7 @@ class VendorExclusionRule {
     priority = 50;
     enabled = true;
     canBeOverridden = true;
-    overridableBy = ['sku_match', 'calculated_sku_match', 'alt_sku_match'];
+    overridableBy = ['sku_match', 'calculated_sku_match', 'alt_sku_match', 'match_confirmation_override'];
     evaluate(context) {
         const nots = [];
         const formatted = context.vendorScrapeOptions.default_skip_vendors
@@ -1053,7 +1070,7 @@ class BrandMismatchRule {
     priority = 40;
     enabled = true;
     canBeOverridden = true;
-    overridableBy = ['sku_match', 'calculated_sku_match', 'alt_sku_match'];
+    overridableBy = ['sku_match', 'calculated_sku_match', 'alt_sku_match', 'match_confirmation_override'];
     evaluate(context) {
         if (!context.result.brand) {
             return null;
@@ -1116,7 +1133,7 @@ class CalculatedSkuMismatchRule {
     priority = 30;
     enabled = true;
     canBeOverridden = true;
-    overridableBy = ['sku_match', 'calculated_sku_match', 'alt_sku_match'];
+    overridableBy = ['sku_match', 'calculated_sku_match', 'alt_sku_match', 'match_confirmation_override'];
     evaluate(context) {
         const result = context.result;
         if (!result.calculated_sku) {
@@ -1159,7 +1176,7 @@ class AISkuMismatchRule {
     priority = 30;
     enabled = true;
     canBeOverridden = true;
-    overridableBy = ['sku_match', 'calculated_sku_match', 'alt_sku_match'];
+    overridableBy = ['sku_match', 'calculated_sku_match', 'alt_sku_match', 'match_confirmation_override'];
     evaluate(context) {
         const result = context.result;
         if (!result.ai_extracted_sku) {
@@ -1202,7 +1219,7 @@ class CriticalSpecMismatchRule {
     priority = 35;
     enabled = true;
     canBeOverridden = true;
-    overridableBy = ['sku_match', 'calculated_sku_match', 'alt_sku_match'];
+    overridableBy = ['sku_match', 'calculated_sku_match', 'alt_sku_match', 'match_confirmation_override'];
     evaluate(context) {
         if (!context.result.regexUnitResults || !context.variant.regexUnitResults) {
             return null;
@@ -1231,7 +1248,7 @@ class RefurbishedUsedRule {
     priority = 25;
     enabled = true;
     canBeOverridden = true;
-    overridableBy = [];
+    overridableBy = ['match_confirmation_override'];
     evaluate(context) {
         const refurbishedKeywords = getRefurbishedKeywords(context.variant);
         const normalizedTitle = context.result.title?.toLowerCase().replace(/[^a-z0-9-]/g, ' ') ?? '';
@@ -1439,6 +1456,49 @@ class ProductIdMatchOverrideRule {
 // ===============================
 // Registry Factory
 // ===============================
+/**
+ * Override rule for manually confirmed matches
+ */
+class MatchConfirmationOverrideRule {
+    id = 'match_confirmation_override';
+    name = 'Match Confirmation Override';
+    description = 'Overrides hide reasons when a match has been manually confirmed via matchConfirmationMap';
+    severity = FilterSeverity.INFO;
+    priority = 300;
+    enabled = true;
+    canBeOverridden = false;
+    overridableBy = [];
+    evaluate(context) {
+        if (!context.matchConfirmationMap) {
+            return null;
+        }
+        const result = context.result;
+        if (!result.listing_hash) {
+            return null;
+        }
+        const variantId = String(context.variant.id);
+        const confirmation = context.matchConfirmationMap[variantId]?.[result.listing_hash];
+        if (!confirmation) {
+            return null;
+        }
+        return {
+            ruleId: this.id,
+            severity: this.severity,
+            message: HIDE_OVERRIDE_REASONS.MATCH_CONFIRMATION,
+            metadata: {
+                isOverride: true,
+                listingHash: result.listing_hash,
+                confirmationSource: confirmation.confirmation_source,
+                confirmedBy: confirmation.confirmed_by,
+                confirmedAt: confirmation.confirmed_at,
+            },
+            timestamp: new Date().toISOString(),
+        };
+    }
+}
+// ===============================
+// Registry Factory
+// ===============================
 /**
  * Create and populate a registry with all built-in rules
  */
@@ -1468,6 +1528,7 @@ export function createDefaultFilterRegistry() {
     registry.registerRule(new CalculatedSkuMatchOverrideRule());
     registry.registerRule(new AltSkuMatchOverrideRule());
     registry.registerRule(new ProductIdMatchOverrideRule());
+    registry.registerRule(new MatchConfirmationOverrideRule());
     return registry;
 }
 /**
@@ -1559,7 +1620,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, }) => {
+export const filterScrapeResultsV2 = ({ scrapeResults, variant, variantScrapeOptions, vendorScrapeOptions, globalScrapeOptions, filterConfig, customRules, comparisonMap, matchConfirmationMap, }) => {
     const registry = createDefaultFilterRegistry();
     // Register custom rules if provided
     if (customRules) {
@@ -1574,7 +1635,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);
+    results = engine.evaluateBatch(results, variant, variantScrapeOptions, vendorScrapeOptions, globalScrapeOptions, comparisonMap, matchConfirmationMap);
     return results;
 };
 /**
@@ -2161,3 +2222,72 @@ export function findUnitVariations(data) {
     });
     return results;
 }
+/**
+ * Derives the high-confidence matched results (shownResults) from a MatchResult.
+ * Includes candidates at or above minConfidence whose visibility state is not HIDDEN,
+ * plus HIDDEN candidates whose filter rules are all confidence-overridable and whose
+ * 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?.map((fr) => fr.ruleId).includes('match_confirmation_override')) {
+            shownResults.push(foundResult);
+        }
+    });
+    shownResults.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;
+}
+/**
+ * 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.
+ * Results are sorted by price ascending.
+ */
+export function getNeedsReviewResults(matchResult, sortedResults, shownResults, variantPrice, minConfidence, reviewConfidenceMin) {
+    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;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@factorypure/client-helpers",
-    "version": "1.1.24",
+    "version": "1.1.26",
     "description": "",
     "main": "./dist/index.js",
     "types": "./dist/index.d.ts",
@@ -20,6 +20,7 @@
         "typescript": "^5.6.2"
     },
     "dependencies": {
+        "@factorypure/matching-engine": "^1.0.8",
         "@types/date-fns": "^2.5.3",
         "date-fns": "^4.1.0",
         "flexsearch": "^0.8.212",