@factorypure/client-helpers 1.1.8 → 1.1.9

package/dist/index.d.ts

@@ -1,4 +1,171 @@
 import { z } from 'zod';
+/**
+ * @packageDocumentation
+ * @module @factorypure/client-helpers
+ *
+ * # Filter System v2
+ *
+ * This package provides an extensible, rule-based filtering system for scrape results.
+ *
+ * ## Key Concepts
+ *
+ * ### Filter Severity
+ * - **BLOCK**: Always hides the result, cannot be overridden
+ * - **WARNING**: Shows result with warning indicator, can be overridden by override rules
+ * - **INFO**: Metadata only, doesn't affect visibility
+ *
+ * ### Visibility States
+ * - **HIDDEN**: Result is filtered out
+ * - **VISIBLE_WITH_WARNINGS**: Result is shown but has warning indicators
+ * - **VISIBLE**: Result is shown without issues
+ *
+ * ### Filter Rules
+ * Rules implement the FilterRule interface and are evaluated against results.
+ * Each rule can:
+ * - Have a severity level (BLOCK, WARNING, INFO)
+ * - Have a priority (higher priority rules evaluated first)
+ * - Be enabled/disabled
+ * - Specify which override rules can override it
+ *
+ * ### Override Rules
+ * Special INFO-level rules that can override WARNING-level rules.
+ * Examples: SKU match, calculated SKU match, alternate SKU match
+ *
+ * ## Quick Start
+ *
+ * ### Using the Default Engine
+ * ```typescript
+ * import { filterScrapeResultsV2, createDefaultFilterEngine } from '@factorypure/client-helpers'
+ *
+ * const filteredResults = filterScrapeResultsV2({
+ *   scrapeResults,
+ *   variant,
+ *   variantScrapeOptions,
+ *   vendorScrapeOptions,
+ *   globalScrapeOptions,
+ * })
+ * ```
+ *
+ * ### Custom Configuration
+ * ```typescript
+ * const filteredResults = filterScrapeResultsV2({
+ *   scrapeResults,
+ *   variant,
+ *   variantScrapeOptions,
+ *   vendorScrapeOptions,
+ *   globalScrapeOptions,
+ *   filterConfig: {
+ *     rules: [
+ *       { id: 'high_price_outlier', enabled: false },
+ *       { id: 'competitor_exclusion', severity: FilterSeverity.BLOCK },
+ *       { id: 'refurbished_used', priority: 100 },
+ *     ]
+ *   }
+ * })
+ * ```
+ *
+ * ### Adding Custom Rules
+ * ```typescript
+ * import { createCustomFilterRule, FilterSeverity } from '@factorypure/client-helpers'
+ *
+ * const myCustomRule = createCustomFilterRule({
+ *   id: 'my_custom_rule',
+ *   name: 'My Custom Rule',
+ *   description: 'Filters results based on custom logic',
+ *   severity: FilterSeverity.WARNING,
+ *   priority: 50,
+ *   canBeOverridden: true,
+ *   overridableBy: ['sku_match'],
+ *   evaluate: (context) => {
+ *     if (context.result.title.includes('bad-keyword')) {
+ *       return {
+ *         ruleId: 'my_custom_rule',
+ *         severity: FilterSeverity.WARNING,
+ *         message: 'Contains bad keyword',
+ *         metadata: { keyword: 'bad-keyword' },
+ *         timestamp: new Date().toISOString(),
+ *       }
+ *     }
+ *     return null
+ *   }
+ * })
+ *
+ * const filteredResults = filterScrapeResultsV2({
+ *   scrapeResults,
+ *   variant,
+ *   variantScrapeOptions,
+ *   vendorScrapeOptions,
+ *   globalScrapeOptions,
+ *   customRules: [myCustomRule],
+ * })
+ * ```
+ *
+ * ### Using the Builder Pattern
+ * ```typescript
+ * import { FilterRuleBuilder, FilterSeverity } from '@factorypure/client-helpers'
+ *
+ * const myRule = new FilterRuleBuilder()
+ *   .id('price_above_threshold')
+ *   .name('Price Above Threshold')
+ *   .description('Filters results above a price threshold')
+ *   .severity(FilterSeverity.WARNING)
+ *   .priority(80)
+ *   .canBeOverridden(true)
+ *   .overridableBy(['sku_match'])
+ *   .evaluate((context) => {
+ *     if (context.result.extracted_price > 10000) {
+ *       return {
+ *         ruleId: 'price_above_threshold',
+ *         severity: FilterSeverity.WARNING,
+ *         message: 'Price exceeds $10,000',
+ *         metadata: { price: context.result.extracted_price },
+ *         timestamp: new Date().toISOString(),
+ *       }
+ *     }
+ *     return null
+ *   })
+ *   .build()
+ * ```
+ *
+ * ## Built-in Rules
+ *
+ * ### Block Rules (Cannot be overridden)
+ * - `high_price_outlier`: Filters results >15% more expensive than variant
+ * - `low_price_outlier`: Filters results significantly cheaper than variant
+ * - `date_outlier`: Filters results outside date window
+ * - `duplicate`: Filters duplicate results
+ * - `scam_source_exclusion`: Filters known scam sources
+ * - `manually_ignored`: Filters manually ignored/excluded results
+ * - `out_of_stock`: Filters out of stock items
+ *
+ * ### Warning Rules (Can be overridden)
+ * - `competitor_exclusion`: Filters excluded competitors
+ * - `search_exclusion`: Filters results not matching search criteria
+ * - `skip_sku`: Filters results with SKUs from skip list
+ * - `vendor_exclusion`: Filters results with excluded vendor names
+ * - `brand_mismatch`: Filters results with mismatched brands
+ * - `calculated_sku_mismatch`: Filters results with mismatched calculated SKUs
+ * - `critical_spec_mismatch`: Filters results with mismatched critical specs
+ * - `refurbished_used`: Filters refurbished/used items
+ *
+ * ### Override Rules
+ * - `sku_match`: SKU found in title
+ * - `calculated_sku_match`: Calculated SKU matches variant SKU
+ * - `alt_sku_match`: Alternate SKU matches
+ * - `product_id_match`: Product ID is linked
+ *
+ * ## Migration from Legacy System
+ *
+ * The legacy `filterScrapeResults` function is still available for backward compatibility.
+ * Results include both old fields (`hide_reasons`, `hide_override_reasons`) and new fields
+ * (`filter_results`, `visibility_state`) during the transition period.
+ *
+ * To migrate:
+ * 1. Replace `filterScrapeResults` with `filterScrapeResultsV2`
+ * 2. Update code to use `visibility_state` instead of `ignore_result`
+ * 3. Use `filter_results` for detailed filter information instead of string arrays
+ * 4. Configure rules as needed using `filterConfig` parameter
+ */
 export declare const regexUnitResultSchema: z.ZodObject<{
     value: z.ZodString;
     source: z.ZodString;
@@ -70,6 +237,36 @@ export type RegexUnitResultType = z.infer<typeof regexUnitResultSchema>;
 export type RegexUnitResultsType = z.infer<typeof regexUnitResultsSchema> & {
     [key: string]: RegexUnitResultType[];
 };
+/**
+ * Severity levels for filter rules
+ * - BLOCK: Always hides the result, cannot be overridden
+ * - WARNING: Shows result with warning indicator, can be overridden
+ * - INFO: Metadata only, doesn't affect visibility
+ */
+export declare enum FilterSeverity {
+    BLOCK = "BLOCK",
+    WARNING = "WARNING",
+    INFO = "INFO"
+}
+/**
+ * Visibility states for results after filter evaluation
+ */
+export declare enum VisibilityState {
+    HIDDEN = "HIDDEN",
+    VISIBLE_WITH_WARNINGS = "VISIBLE_WITH_WARNINGS",
+    VISIBLE = "VISIBLE"
+}
+/**
+ * Structured result from a filter rule evaluation
+ */
+export declare const filterResultSchema: z.ZodObject<{
+    ruleId: z.ZodString;
+    severity: z.ZodEnum<typeof FilterSeverity>;
+    message: z.ZodString;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    timestamp: z.ZodString;
+}, z.core.$strip>;
+export type FilterResult = z.infer<typeof filterResultSchema>;
 export declare const scrapeResultsSchema: z.ZodObject<{
     id: z.ZodNumber;
     scrape_id: z.ZodNumber;
@@ -105,6 +302,14 @@ export declare const scrapeResultsSchema: z.ZodObject<{
     ignore_reasons: z.ZodArray<z.ZodString>;
     hide_reasons: z.ZodArray<z.ZodString>;
     hide_override_reasons: z.ZodArray<z.ZodString>;
+    filter_results: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        ruleId: z.ZodString;
+        severity: z.ZodEnum<typeof FilterSeverity>;
+        message: z.ZodString;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+        timestamp: z.ZodString;
+    }, z.core.$strip>>>;
+    visibility_state: z.ZodOptional<z.ZodEnum<typeof VisibilityState>>;
     regexUnitResults: z.ZodNullable<z.ZodObject<{
         inch: z.ZodArray<z.ZodObject<{
             value: z.ZodString;
@@ -229,6 +434,14 @@ export declare const immersiveScrapeResultsSchema: z.ZodObject<{
     ignore_reasons: z.ZodArray<z.ZodString>;
     hide_reasons: z.ZodArray<z.ZodString>;
     hide_override_reasons: z.ZodArray<z.ZodString>;
+    filter_results: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        ruleId: z.ZodString;
+        severity: z.ZodEnum<typeof FilterSeverity>;
+        message: z.ZodString;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+        timestamp: z.ZodString;
+    }, z.core.$strip>>>;
+    visibility_state: z.ZodOptional<z.ZodEnum<typeof VisibilityState>>;
     brand: z.ZodNullable<z.ZodString>;
     company_id: z.ZodNullable<z.ZodNumber>;
     regexUnitResults: z.ZodNullable<z.ZodObject<{
@@ -363,6 +576,66 @@ export declare const globalScrapeOptionsSchema: z.ZodObject<{
     scam_sources: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
 export type GlobalScrapeOptionsType = z.infer<typeof globalScrapeOptionsSchema>;
+/**
+ * Context provided to filter rules during evaluation
+ */
+export type FilterContext<T = ScrapeResultsType | ImmersiveScrapeResultsType> = {
+    result: T;
+    variant: {
+        id: number;
+        title: string;
+        sku: string;
+        price: number;
+        vendor: string;
+        regexUnitResults?: RegexUnitResultsType;
+        found_product_ids?: string[];
+    };
+    variantScrapeOptions: VariantScrapeOptionsType;
+    vendorScrapeOptions: VendorScrapeOptionsType;
+    globalScrapeOptions: GlobalScrapeOptionsType;
+};
+/**
+ * Base interface for filter rules
+ */
+export interface FilterRule<T = ScrapeResultsType | ImmersiveScrapeResultsType> {
+    id: string;
+    name: string;
+    description: string;
+    severity: FilterSeverity;
+    priority: number;
+    enabled: boolean;
+    canBeOverridden: boolean;
+    overridableBy: string[];
+    /**
+     * Evaluate the rule against a result
+     * @returns FilterResult if rule triggers, null if rule doesn't apply
+     */
+    evaluate(context: FilterContext<T>): FilterResult | null;
+}
+/**
+ * Configuration for a filter rule (serializable)
+ */
+export type FilterRuleConfig = {
+    id: string;
+    enabled?: boolean;
+    severity?: FilterSeverity;
+    priority?: number;
+    parameters?: Record<string, any>;
+};
+/**
+ * Overall filter configuration
+ */
+export declare const filterConfigurationSchema: z.ZodObject<{
+    rules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        severity: z.ZodOptional<z.ZodEnum<typeof FilterSeverity>>;
+        priority: z.ZodOptional<z.ZodNumber>;
+        parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    }, z.core.$strip>>>;
+    globalParameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, z.core.$strip>;
+export type FilterConfiguration = z.infer<typeof filterConfigurationSchema>;
 export declare const HIDE_REASONS: {
     IGNORED: string;
     HIGH_PRICE_OUTLIER: string;
@@ -391,6 +664,114 @@ export declare const HIDE_OVERRIDE_REASONS: {
 };
 export declare const TOO_CHEAP_MULTIPLIER = 0.75;
 export declare const TOO_EXPENSIVE_MULTIPLIER = 1.15;
+/**
+ * Registry for filter rules with configuration management
+ */
+export declare class FilterRuleRegistry {
+    private rules;
+    private configurations;
+    /**
+     * Register a new filter rule
+     */
+    registerRule(rule: FilterRule): void;
+    /**
+     * Get a rule by ID
+     */
+    getRule(id: string): FilterRule | undefined;
+    /**
+     * Get all registered rules
+     */
+    getAllRules(): FilterRule[];
+    /**
+     * Get all enabled rules sorted by priority
+     */
+    getEnabledRules(): FilterRule[];
+    /**
+     * Apply configuration to rules
+     */
+    applyConfiguration(config: FilterConfiguration): void;
+    /**
+     * Get effective configuration for a rule
+     */
+    getRuleConfig(ruleId: string): FilterRuleConfig | undefined;
+}
+/**
+ * Engine for evaluating filter rules and determining visibility
+ */
+export declare class FilterEngine {
+    private registry;
+    constructor(registry: FilterRuleRegistry);
+    /**
+     * Evaluate all rules for a single result
+     */
+    evaluateResult<T extends ScrapeResultsType | ImmersiveScrapeResultsType>(context: FilterContext<T>): FilterResult[];
+    /**
+     * Evaluate rules for a batch of results
+     */
+    evaluateBatch<T extends ScrapeResultsType | ImmersiveScrapeResultsType>(results: T[], variant: FilterContext<T>['variant'], variantScrapeOptions: VariantScrapeOptionsType, vendorScrapeOptions: VendorScrapeOptionsType, globalScrapeOptions: GlobalScrapeOptionsType): T[];
+    /**
+     * Calculate visibility state based on filter results
+     */
+    calculateVisibility(filterResults: FilterResult[]): VisibilityState;
+}
+/**
+ * Create and populate a registry with all built-in rules
+ */
+export declare function createDefaultFilterRegistry(): FilterRuleRegistry;
+/**
+ * Create a filter engine with default configuration
+ */
+export declare function createDefaultFilterEngine(config?: FilterConfiguration): FilterEngine;
+/**
+ * Builder for creating custom filter rules
+ */
+export declare class FilterRuleBuilder {
+    private rule;
+    id(id: string): this;
+    name(name: string): this;
+    description(description: string): this;
+    severity(severity: FilterSeverity): this;
+    priority(priority: number): this;
+    enabled(enabled: boolean): this;
+    canBeOverridden(canBeOverridden: boolean): this;
+    overridableBy(ruleIds: string[]): this;
+    evaluate(evaluateFn: (context: FilterContext) => FilterResult | null): this;
+    build(): FilterRule;
+}
+/**
+ * Simple factory for creating custom rules without implementing the full interface
+ */
+export declare function createCustomFilterRule(config: {
+    id: string;
+    name: string;
+    description: string;
+    severity: FilterSeverity;
+    priority?: number;
+    canBeOverridden?: boolean;
+    overridableBy?: string[];
+    evaluate: (context: FilterContext) => FilterResult | null;
+}): FilterRule;
+/**
+ * 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, }: {
+    scrapeResults: T[];
+    variant: {
+        id: number;
+        title: string;
+        sku: string;
+        price: number;
+        vendor: string;
+        regexUnitResults?: RegexUnitResultsType;
+        found_product_ids?: string[];
+    };
+    variantScrapeOptions: VariantScrapeOptionsType;
+    vendorScrapeOptions: VendorScrapeOptionsType;
+    globalScrapeOptions: GlobalScrapeOptionsType;
+    filterConfig?: FilterConfiguration;
+    customRules?: FilterRule[];
+}) => T[];
 export declare const filterScrapeResults: <T extends ScrapeResultsType | ImmersiveScrapeResultsType>({ scrapeResults, variant, variantScrapeOptions, vendorScrapeOptions, globalScrapeOptions, }: {
     scrapeResults: T[];
     variant: {