@startsimpli/funnels 0.1.2

package/dist/index-BGDEXbuz.d.ts

@@ -0,0 +1,434 @@
+/**
+ * @startsimpli/funnels - BRUTALLY GENERIC Funnel Type System
+ *
+ * This type system works for ANY entity type:
+ * - Investors, firms, contacts, organizations
+ * - Recipes, ingredients, users
+ * - Leads, tasks, projects
+ * - GitHub repos, pull requests, issues
+ *
+ * Zero domain-specific types. All filtering is based on field paths and operators.
+ */
+/**
+ * Filter operators - works with any data type
+ */
+type Operator = 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'contains' | 'not_contains' | 'startswith' | 'endswith' | 'matches' | 'in' | 'not_in' | 'has_any' | 'has_all' | 'isnull' | 'isnotnull' | 'has_tag' | 'not_has_tag' | 'is_true' | 'is_false';
+/**
+ * Field data types - for operator validation
+ */
+type FieldType = 'string' | 'number' | 'boolean' | 'date' | 'array' | 'object' | 'tag' | 'any';
+/**
+ * A single filter rule
+ *
+ * Examples:
+ * - { field_path: 'firm.stage', operator: 'eq', value: 'Series A' }
+ * - { field_path: 'recipe.cuisine', operator: 'in', value: ['Italian', 'French'] }
+ * - { field_path: 'contact.email', operator: 'isnotnull', value: null }
+ * - { field_path: 'organization.tags', operator: 'has_tag', value: 'enterprise' }
+ */
+interface FilterRule {
+    /**
+     * Dot-notation path to field
+     * Examples: 'name', 'firm.stage', 'profile.linkedin_url', 'tags', 'metrics.arr_usd'
+     */
+    field_path: string;
+    /** Comparison operator */
+    operator: Operator;
+    /**
+     * Value to compare against
+     * Type depends on operator:
+     * - eq/ne/gt/lt/gte/lte: any primitive
+     * - contains/startswith/endswith: string
+     * - in/not_in: array
+     * - isnull/isnotnull: null (value ignored)
+     * - has_tag/not_has_tag: string (tag name)
+     */
+    value: any;
+    /**
+     * Optional: negate the rule result
+     * Default: false
+     */
+    negate?: boolean;
+}
+/**
+ * Filter logic for combining rules
+ */
+type FilterLogic = 'AND' | 'OR';
+/**
+ * Action to take when stage rules match
+ */
+type MatchAction = 'continue' | 'tag' | 'tag_continue' | 'output';
+/**
+ * Action to take when stage rules don't match
+ */
+type NoMatchAction = 'continue' | 'exclude' | 'tag_exclude';
+/**
+ * A single stage in a funnel
+ *
+ * Generic over entity type TEntity
+ */
+interface FunnelStage<TEntity = any> {
+    /** Unique stage identifier */
+    id: string;
+    /** Stage execution order (0-indexed) */
+    order: number;
+    /** Human-readable stage name */
+    name: string;
+    /** Optional description */
+    description?: string;
+    /**
+     * How to combine filter rules
+     * - AND: All rules must match
+     * - OR: At least one rule must match
+     */
+    filter_logic: FilterLogic;
+    /** Filter rules to evaluate */
+    rules: FilterRule[];
+    /** Action when rules match */
+    match_action: MatchAction;
+    /** Action when rules don't match */
+    no_match_action: NoMatchAction;
+    /** Tags to add when rules match */
+    match_tags?: string[];
+    /** Tags to add when rules don't match */
+    no_match_tags?: string[];
+    /**
+     * Context to add to entity when rules match
+     * Can be used to track why entity matched
+     * Examples:
+     * - { stage: 'qualified_leads', reason: 'high_fit_score' }
+     * - { tier: 'premium', discount: 0.2 }
+     */
+    match_context?: Record<string, any>;
+    /**
+     * Optional: Custom evaluation function
+     * For complex logic that can't be expressed with rules
+     */
+    custom_evaluator?: (entity: TEntity) => boolean;
+}
+/**
+ * Funnel status
+ */
+type FunnelStatus = 'draft' | 'active' | 'paused' | 'archived';
+/**
+ * Input entity types
+ */
+type InputType = 'contacts' | 'organizations' | 'both' | 'any';
+/**
+ * A complete funnel definition
+ *
+ * Generic over entity type TEntity
+ */
+interface Funnel<TEntity = any> {
+    /** Unique funnel identifier */
+    id: string;
+    /** Human-readable funnel name */
+    name: string;
+    /** Optional description */
+    description?: string;
+    /** Funnel status */
+    status: FunnelStatus;
+    /**
+     * Type of entities this funnel processes
+     * Used for field registry lookup
+     */
+    input_type: InputType;
+    /** Ordered stages */
+    stages: FunnelStage<TEntity>[];
+    /** Created timestamp */
+    created_at: Date | string;
+    /** Last updated timestamp */
+    updated_at: Date | string;
+    /** Owner user ID */
+    owner_id?: string;
+    /** Team/company ID for multi-tenancy */
+    team_id?: string;
+    /**
+     * Optional: Tags to automatically add to all entities
+     * that complete the funnel
+     */
+    completion_tags?: string[];
+    /**
+     * Optional: Metadata for custom integrations
+     */
+    metadata?: Record<string, any>;
+}
+/**
+ * Funnel run status
+ */
+type FunnelRunStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+/**
+ * How the funnel run was triggered
+ */
+type TriggerType = 'manual' | 'scheduled' | 'webhook' | 'api';
+/**
+ * Statistics for a single stage execution
+ */
+interface StageStats {
+    /** Stage ID */
+    stage_id: string;
+    /** Stage name */
+    stage_name: string;
+    /** Entities that entered this stage */
+    input_count: number;
+    /** Entities that matched rules */
+    matched_count: number;
+    /** Entities that didn't match rules */
+    not_matched_count: number;
+    /** Entities excluded at this stage */
+    excluded_count: number;
+    /** Entities tagged at this stage */
+    tagged_count: number;
+    /** Entities that continued to next stage */
+    continued_count: number;
+    /** Execution time in milliseconds */
+    duration_ms?: number;
+    /** Error count */
+    error_count?: number;
+}
+/**
+ * A funnel execution run
+ */
+interface FunnelRun {
+    /** Unique run identifier */
+    id: string;
+    /** Funnel ID */
+    funnel_id: string;
+    /** Funnel snapshot (copy of funnel at run time) */
+    funnel?: Funnel;
+    /** Run status */
+    status: FunnelRunStatus;
+    /** How run was triggered */
+    trigger_type: TriggerType;
+    /** User who triggered (if manual) */
+    triggered_by?: string;
+    /** Started timestamp */
+    started_at: Date | string;
+    /** Completed timestamp */
+    completed_at?: Date | string;
+    /** Duration in milliseconds */
+    duration_ms?: number;
+    /** Total entities input */
+    total_input: number;
+    /** Total entities matched (in output) */
+    total_matched: number;
+    /** Total entities excluded */
+    total_excluded: number;
+    /** Total entities tagged */
+    total_tagged: number;
+    /** Per-stage statistics */
+    stage_stats: Record<string, StageStats>;
+    /** Error message (if failed) */
+    error?: string;
+    /** Stack trace (if failed) */
+    stack_trace?: string;
+    /** Metadata */
+    metadata?: Record<string, any>;
+}
+/**
+ * Result for a single entity processed through funnel
+ */
+interface FunnelResult<TEntity = any> {
+    /** The entity that was processed */
+    entity: TEntity;
+    /** Whether entity matched and is in output */
+    matched: boolean;
+    /** Stage where entity was excluded (if excluded) */
+    excluded_at_stage?: string;
+    /** Tags accumulated during processing */
+    accumulated_tags: string[];
+    /** Context accumulated during processing */
+    context: Record<string, any>;
+    /** Stage-by-stage results */
+    stage_results?: StageResult[];
+}
+/**
+ * Result for a single stage evaluation
+ */
+interface StageResult {
+    /** Stage ID */
+    stage_id: string;
+    /** Stage name */
+    stage_name: string;
+    /** Whether rules matched */
+    matched: boolean;
+    /** Rule evaluation results */
+    rule_results?: RuleResult[];
+    /** Action taken */
+    action: MatchAction | NoMatchAction;
+    /** Tags added */
+    tags_added?: string[];
+    /** Context added */
+    context_added?: Record<string, any>;
+    /** Whether entity was excluded */
+    excluded: boolean;
+    /** Whether entity continued to next stage */
+    continued: boolean;
+}
+/**
+ * Result for a single rule evaluation
+ */
+interface RuleResult {
+    /** Rule field path */
+    field_path: string;
+    /** Rule operator */
+    operator: Operator;
+    /** Value compared against */
+    value: any;
+    /** Actual value from entity */
+    actual_value: any;
+    /** Whether rule matched */
+    matched: boolean;
+    /** Error (if evaluation failed) */
+    error?: string;
+}
+/**
+ * Valid operators for a field type
+ */
+type ValidOperators = Operator[];
+/**
+ * Field constraints
+ */
+interface FieldConstraints {
+    /** Minimum value (numbers, dates) */
+    min_value?: number | string;
+    /** Maximum value (numbers, dates) */
+    max_value?: number | string;
+    /** Allowed values (enums) */
+    choices?: any[];
+    /** Regex pattern */
+    pattern?: string;
+    /** Required field */
+    required?: boolean;
+}
+/**
+ * Field definition in registry
+ *
+ * Describes what fields are available for filtering
+ * on a given entity type
+ */
+interface FieldDefinition {
+    /** Unique field identifier (dot-notation path) */
+    name: string;
+    /** Human-readable label */
+    label: string;
+    /** Field data type */
+    type: FieldType;
+    /** Valid operators for this field */
+    operators: ValidOperators;
+    /** Field category (for UI grouping) */
+    category?: string;
+    /** Optional description */
+    description?: string;
+    /** Field constraints */
+    constraints?: FieldConstraints;
+    /** Whether field is sortable */
+    sortable?: boolean;
+    /** Whether field is searchable */
+    searchable?: boolean;
+    /** Example values (for UI help) */
+    examples?: any[];
+    /** Related fields (for UI suggestions) */
+    related_fields?: string[];
+}
+/**
+ * Field registry for an entity type
+ *
+ * Maps field paths to their definitions
+ */
+interface FieldRegistry {
+    /** Entity type this registry is for */
+    entity_type: string;
+    /** Available fields */
+    fields: FieldDefinition[];
+    /** Field lookup by name */
+    field_map?: Map<string, FieldDefinition>;
+    /** Categories (for UI grouping) */
+    categories?: string[];
+}
+/**
+ * Filter configuration (rules + logic)
+ */
+interface FilterConfig {
+    logic: FilterLogic;
+    rules: FilterRule[];
+}
+/**
+ * Partial type helper
+ */
+type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+/**
+ * Extract field paths from object type
+ * Helper for type-safe field path completion
+ */
+type FieldPath<T, Prefix extends string = ''> = {
+    [K in keyof T]: T[K] extends object ? K extends string ? `${Prefix}${K}` | FieldPath<T[K], `${Prefix}${K}.`> : never : K extends string ? `${Prefix}${K}` : never;
+}[keyof T];
+/**
+ * Funnel creation input (omits auto-generated fields)
+ */
+type CreateFunnelInput<TEntity = any> = Omit<Funnel<TEntity>, 'id' | 'created_at' | 'updated_at'>;
+/**
+ * Funnel update input (all fields optional except id)
+ */
+type UpdateFunnelInput<TEntity = any> = DeepPartial<Funnel<TEntity>> & {
+    id: string;
+};
+/**
+ * Stage creation input
+ */
+type CreateStageInput<TEntity = any> = Omit<FunnelStage<TEntity>, 'id'>;
+/**
+ * Stage update input
+ */
+type UpdateStageInput<TEntity = any> = DeepPartial<FunnelStage<TEntity>> & {
+    id: string;
+};
+/**
+ * Type guard: is value a valid Funnel?
+ */
+declare function isFunnel<TEntity = any>(value: unknown): value is Funnel<TEntity>;
+/**
+ * Type guard: is value a valid FunnelStage?
+ */
+declare function isStage<TEntity = any>(value: unknown): value is FunnelStage<TEntity>;
+/**
+ * Type guard: is value a valid FilterRule?
+ */
+declare function isFilterRule(value: unknown): value is FilterRule;
+/**
+ * Type guard: is value a valid FunnelRun?
+ */
+declare function isFunnelRun(value: unknown): value is FunnelRun;
+/**
+ * Type guard: is value a valid FunnelResult?
+ */
+declare function isFunnelResult<TEntity = any>(value: unknown): value is FunnelResult<TEntity>;
+/**
+ * Type guard: is value a valid FieldDefinition?
+ */
+declare function isFieldDefinition(value: unknown): value is FieldDefinition;
+/**
+ * Get valid operators for a field type
+ */
+declare function getValidOperators(fieldType: FieldType): ValidOperators;
+/**
+ * Validate operator is allowed for field type
+ */
+declare function isValidOperator(operator: Operator, fieldType: FieldType): boolean;
+/**
+ * Validate filter rule
+ */
+declare function validateFilterRule(rule: FilterRule): string[];
+/**
+ * Validate funnel stage
+ */
+declare function validateStage<TEntity = any>(stage: FunnelStage<TEntity>): string[];
+/**
+ * Validate funnel
+ */
+declare function validateFunnel<TEntity = any>(funnel: Funnel<TEntity>): string[];
+
+export { validateStage as A, type CreateFunnelInput as C, type DeepPartial as D, type FieldConstraints as F, type InputType as I, type MatchAction as M, type NoMatchAction as N, type Operator as O, type RuleResult as R, type StageResult as S, type TriggerType as T, type UpdateFunnelInput as U, type ValidOperators as V, type CreateStageInput as a, type FieldDefinition as b, type FieldPath as c, type FieldRegistry as d, type FieldType as e, type FilterConfig as f, type FilterLogic as g, type FilterRule as h, type Funnel as i, type FunnelResult as j, type FunnelRun as k, type FunnelRunStatus as l, type FunnelStage as m, type FunnelStatus as n, type StageStats as o, type UpdateStageInput as p, getValidOperators as q, isFieldDefinition as r, isFilterRule as s, isFunnel as t, isFunnelResult as u, isFunnelRun as v, isStage as w, isValidOperator as x, validateFilterRule as y, validateFunnel as z };