@startsimpli/funnels 0.1.3 → 0.1.5

package/src/types/index.ts

@@ -0,0 +1,843 @@
+/**
+ * @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.
+ */
+
+// ============================================================================
+// Core Operators
+// ============================================================================
+
+/**
+ * Filter operators - works with any data type
+ */
+export type Operator =
+  // Equality
+  | 'eq'              // Equal to
+  | 'ne'              // Not equal to
+
+  // Comparison (numbers, dates, strings)
+  | 'gt'              // Greater than
+  | 'lt'              // Less than
+  | 'gte'             // Greater than or equal
+  | 'lte'             // Less than or equal
+
+  // String operations
+  | 'contains'        // String contains substring
+  | 'not_contains'    // String does not contain substring
+  | 'startswith'      // String starts with
+  | 'endswith'        // String ends with
+  | 'matches'         // Regex match
+
+  // Array/Set operations
+  | 'in'              // Value is in array
+  | 'not_in'          // Value is not in array
+  | 'has_any'         // Array has any of these values
+  | 'has_all'         // Array has all of these values
+
+  // Null checks
+  | 'isnull'          // Field is null/undefined
+  | 'isnotnull'       // Field is not null/undefined
+
+  // Tag operations
+  | 'has_tag'         // Entity has tag
+  | 'not_has_tag'     // Entity does not have tag
+
+  // Boolean
+  | 'is_true'         // Boolean is true
+  | 'is_false';       // Boolean is false
+
+/**
+ * Field data types - for operator validation
+ */
+export type FieldType =
+  | 'string'
+  | 'number'
+  | 'boolean'
+  | 'date'
+  | 'array'
+  | 'object'
+  | 'tag'
+  | 'any';
+
+// ============================================================================
+// Filter Rules
+// ============================================================================
+
+/**
+ * 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' }
+ */
+export 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
+ */
+export type FilterLogic = 'AND' | 'OR';
+
+/**
+ * Action to take when stage rules match
+ */
+export type MatchAction =
+  | 'continue'        // Continue to next stage
+  | 'tag'             // Add tags and stop processing
+  | 'tag_continue'    // Add tags and continue to next stage
+  | 'output';         // Add to output and stop processing
+
+/**
+ * Action to take when stage rules don't match
+ */
+export type NoMatchAction =
+  | 'continue'        // Continue to next stage
+  | 'exclude'         // Exclude from output and stop processing
+  | 'tag_exclude';    // Add tags, exclude from output, stop processing
+
+// ============================================================================
+// Funnel Stages
+// ============================================================================
+
+/**
+ * A single stage in a funnel
+ *
+ * Generic over entity type TEntity
+ */
+export 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 Definition
+// ============================================================================
+
+/**
+ * Funnel status
+ */
+export type FunnelStatus = 'draft' | 'active' | 'paused' | 'archived';
+
+/**
+ * Input entity types
+ */
+export type InputType = 'contacts' | 'organizations' | 'both' | 'any';
+
+/**
+ * A complete funnel definition
+ *
+ * Generic over entity type TEntity
+ */
+export 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 Execution
+// ============================================================================
+
+/**
+ * Funnel run status
+ */
+export type FunnelRunStatus =
+  | 'pending'       // Queued, not started
+  | 'running'       // Currently executing
+  | 'completed'     // Finished successfully
+  | 'failed'        // Error occurred
+  | 'cancelled';    // Manually stopped
+
+/**
+ * How the funnel run was triggered
+ */
+export type TriggerType =
+  | 'manual'        // User initiated
+  | 'scheduled'     // Cron/scheduled run
+  | 'webhook'       // External event
+  | 'api';          // API call
+
+/**
+ * Statistics for a single stage execution
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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;
+}
+
+// ============================================================================
+// Field Registry
+// ============================================================================
+
+/**
+ * Valid operators for a field type
+ */
+export type ValidOperators = Operator[];
+
+/**
+ * Field constraints
+ */
+export 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
+ */
+export 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
+ */
+export 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[];
+}
+
+// ============================================================================
+// Utility Types
+// ============================================================================
+
+/**
+ * Filter configuration (rules + logic)
+ */
+export interface FilterConfig {
+  logic: FilterLogic;
+  rules: FilterRule[];
+}
+
+/**
+ * Partial type helper
+ */
+export 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
+ */
+export 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)
+ */
+export type CreateFunnelInput<TEntity = any> = Omit<
+  Funnel<TEntity>,
+  'id' | 'created_at' | 'updated_at'
+>;
+
+/**
+ * Funnel update input (all fields optional except id)
+ */
+export type UpdateFunnelInput<TEntity = any> = DeepPartial<Funnel<TEntity>> & {
+  id: string;
+};
+
+/**
+ * Stage creation input
+ */
+export type CreateStageInput<TEntity = any> = Omit<FunnelStage<TEntity>, 'id'>;
+
+/**
+ * Stage update input
+ */
+export type UpdateStageInput<TEntity = any> = DeepPartial<FunnelStage<TEntity>> & {
+  id: string;
+};
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+/**
+ * Type guard: is value a valid Funnel?
+ */
+export function isFunnel<TEntity = any>(value: unknown): value is Funnel<TEntity> {
+  const f = value as Funnel<TEntity>;
+  return (
+    typeof f === 'object' &&
+    f !== null &&
+    typeof f.id === 'string' &&
+    typeof f.name === 'string' &&
+    ['draft', 'active', 'paused', 'archived'].includes(f.status) &&
+    Array.isArray(f.stages)
+  );
+}
+
+/**
+ * Type guard: is value a valid FunnelStage?
+ */
+export function isStage<TEntity = any>(value: unknown): value is FunnelStage<TEntity> {
+  const s = value as FunnelStage<TEntity>;
+  return (
+    typeof s === 'object' &&
+    s !== null &&
+    typeof s.id === 'string' &&
+    typeof s.name === 'string' &&
+    typeof s.order === 'number' &&
+    ['AND', 'OR'].includes(s.filter_logic) &&
+    Array.isArray(s.rules)
+  );
+}
+
+/**
+ * Type guard: is value a valid FilterRule?
+ */
+export function isFilterRule(value: unknown): value is FilterRule {
+  const r = value as FilterRule;
+  return (
+    typeof r === 'object' &&
+    r !== null &&
+    typeof r.field_path === 'string' &&
+    typeof r.operator === 'string' &&
+    r.value !== undefined
+  );
+}
+
+/**
+ * Type guard: is value a valid FunnelRun?
+ */
+export function isFunnelRun(value: unknown): value is FunnelRun {
+  const r = value as FunnelRun;
+  return (
+    typeof r === 'object' &&
+    r !== null &&
+    typeof r.id === 'string' &&
+    typeof r.funnel_id === 'string' &&
+    ['pending', 'running', 'completed', 'failed', 'cancelled'].includes(r.status)
+  );
+}
+
+/**
+ * Type guard: is value a valid FunnelResult?
+ */
+export function isFunnelResult<TEntity = any>(
+  value: unknown
+): value is FunnelResult<TEntity> {
+  const r = value as FunnelResult<TEntity>;
+  return (
+    typeof r === 'object' &&
+    r !== null &&
+    r.entity !== undefined &&
+    typeof r.matched === 'boolean' &&
+    Array.isArray(r.accumulated_tags)
+  );
+}
+
+/**
+ * Type guard: is value a valid FieldDefinition?
+ */
+export function isFieldDefinition(value: unknown): value is FieldDefinition {
+  const f = value as FieldDefinition;
+  return (
+    typeof f === 'object' &&
+    f !== null &&
+    typeof f.name === 'string' &&
+    typeof f.label === 'string' &&
+    typeof f.type === 'string' &&
+    Array.isArray(f.operators)
+  );
+}
+
+// ============================================================================
+// Validation Helpers
+// ============================================================================
+
+/**
+ * Get valid operators for a field type
+ */
+export function getValidOperators(fieldType: FieldType): ValidOperators {
+  switch (fieldType) {
+    case 'string':
+      return [
+        'eq', 'ne', 'contains', 'not_contains', 'startswith', 'endswith',
+        'matches', 'in', 'not_in', 'isnull', 'isnotnull'
+      ];
+
+    case 'number':
+      return [
+        'eq', 'ne', 'gt', 'lt', 'gte', 'lte',
+        'in', 'not_in', 'isnull', 'isnotnull'
+      ];
+
+    case 'boolean':
+      return ['eq', 'ne', 'is_true', 'is_false', 'isnull', 'isnotnull'];
+
+    case 'date':
+      return [
+        'eq', 'ne', 'gt', 'lt', 'gte', 'lte',
+        'isnull', 'isnotnull'
+      ];
+
+    case 'array':
+      return [
+        'in', 'not_in', 'has_any', 'has_all',
+        'isnull', 'isnotnull'
+      ];
+
+    case 'tag':
+      return ['has_tag', 'not_has_tag'];
+
+    case 'object':
+      return ['isnull', 'isnotnull'];
+
+    case 'any':
+    default:
+      return [
+        'eq', 'ne', 'gt', 'lt', 'gte', 'lte',
+        'contains', 'not_contains', 'startswith', 'endswith',
+        'in', 'not_in', 'isnull', 'isnotnull'
+      ];
+  }
+}
+
+/**
+ * Validate operator is allowed for field type
+ */
+export function isValidOperator(
+  operator: Operator,
+  fieldType: FieldType
+): boolean {
+  const validOps = getValidOperators(fieldType);
+  return validOps.includes(operator);
+}
+
+/**
+ * Validate filter rule
+ */
+export function validateFilterRule(rule: FilterRule): string[] {
+  const errors: string[] = [];
+
+  if (!rule.field_path) {
+    errors.push('field_path is required');
+  }
+
+  if (!rule.operator) {
+    errors.push('operator is required');
+  }
+
+  // Value required for most operators
+  const nullOps = ['isnull', 'isnotnull', 'is_true', 'is_false'];
+  if (!nullOps.includes(rule.operator) && rule.value === undefined) {
+    errors.push(`value is required for operator '${rule.operator}'`);
+  }
+
+  return errors;
+}
+
+/**
+ * Validate funnel stage
+ */
+export function validateStage<TEntity = any>(
+  stage: FunnelStage<TEntity>
+): string[] {
+  const errors: string[] = [];
+
+  if (!stage.name) {
+    errors.push('name is required');
+  }
+
+  if (typeof stage.order !== 'number') {
+    errors.push('order must be a number');
+  }
+
+  if (!['AND', 'OR'].includes(stage.filter_logic)) {
+    errors.push('filter_logic must be AND or OR');
+  }
+
+  if (!Array.isArray(stage.rules)) {
+    errors.push('rules must be an array');
+  } else {
+    stage.rules.forEach((rule, i) => {
+      const ruleErrors = validateFilterRule(rule);
+      ruleErrors.forEach(err => errors.push(`rules[${i}]: ${err}`));
+    });
+  }
+
+  return errors;
+}
+
+/**
+ * Validate funnel
+ */
+export function validateFunnel<TEntity = any>(
+  funnel: Funnel<TEntity>
+): string[] {
+  const errors: string[] = [];
+
+  if (!funnel.name) {
+    errors.push('name is required');
+  }
+
+  if (!['draft', 'active', 'paused', 'archived'].includes(funnel.status)) {
+    errors.push('status must be draft, active, paused, or archived');
+  }
+
+  if (!Array.isArray(funnel.stages)) {
+    errors.push('stages must be an array');
+  } else {
+    funnel.stages.forEach((stage, i) => {
+      const stageErrors = validateStage(stage);
+      stageErrors.forEach(err => errors.push(`stages[${i}]: ${err}`));
+    });
+
+    // Check stage order is sequential
+    const orders = funnel.stages.map(s => s.order).sort((a, b) => a - b);
+    const expectedOrders = Array.from({ length: orders.length }, (_, i) => i);
+    if (JSON.stringify(orders) !== JSON.stringify(expectedOrders)) {
+      errors.push('stage orders must be sequential starting from 0');
+    }
+  }
+
+  return errors;
+}