@startsimpli/funnels 0.4.13 → 0.4.14

package/src/components/FunnelPreview/example.tsx

@@ -17,7 +17,7 @@ const investorFunnel: Funnel = {
   name: 'Investor Qualification',
   description: 'Filter investors by firm stage and check size',
   status: 'active',
-  inputType: 'contacts',
+  entityType: 'investor',
   stages: [
     {
       id: 'stage-1',
@@ -25,9 +25,9 @@ const investorFunnel: Funnel = {
       name: 'Series A or Later',
       filterLogic: 'OR',
       rules: [
-        { fieldPath: 'firm.stage', operator: 'eq', value: 'Series A' },
-        { fieldPath: 'firm.stage', operator: 'eq', value: 'Series B' },
-        { fieldPath: 'firm.stage', operator: 'eq', value: 'Series C' },
+        { field: 'firm.stage', operator: 'eq', value: 'Series A' },
+        { field: 'firm.stage', operator: 'eq', value: 'Series B' },
+        { field: 'firm.stage', operator: 'eq', value: 'Series C' },
       ],
       matchAction: 'continue',
       noMatchAction: 'exclude',
@@ -37,7 +37,7 @@ const investorFunnel: Funnel = {
       order: 1,
       name: 'High ICP Score',
       filterLogic: 'AND',
-      rules: [{ fieldPath: 'icp_score', operator: 'gte', value: 80 }],
+      rules: [{ field: 'icp_score', operator: 'gte', value: 80 }],
       matchAction: 'output',
       noMatchAction: 'exclude',
     },
@@ -112,14 +112,14 @@ const recipeFunnel: Funnel = {
   name: 'Recipe Recommendations',
   description: 'Filter recipes by dietary restrictions and difficulty',
   status: 'active',
-  inputType: 'any',
+  entityType: 'recipe',
   stages: [
     {
       id: 'dietary',
       order: 0,
       name: 'Vegetarian',
       filterLogic: 'AND',
-      rules: [{ fieldPath: 'tags', operator: 'has_tag', value: 'vegetarian' }],
+      rules: [{ field: 'tags', operator: 'has_tag', value: 'vegetarian' }],
       matchAction: 'continue',
       noMatchAction: 'exclude',
     },
@@ -129,8 +129,8 @@ const recipeFunnel: Funnel = {
       name: 'Easy to Moderate',
       filterLogic: 'OR',
       rules: [
-        { fieldPath: 'difficulty', operator: 'eq', value: 'easy' },
-        { fieldPath: 'difficulty', operator: 'eq', value: 'moderate' },
+        { field: 'difficulty', operator: 'eq', value: 'easy' },
+        { field: 'difficulty', operator: 'eq', value: 'moderate' },
       ],
       matchAction: 'output',
       noMatchAction: 'exclude',
@@ -198,14 +198,14 @@ const leadFunnel: Funnel = {
   name: 'Qualified Leads',
   description: 'Score and filter leads based on company size and engagement',
   status: 'active',
-  inputType: 'any',
+  entityType: 'lead',
   stages: [
     {
       id: 'company-size',
       order: 0,
       name: 'Mid-Market and Above',
       filterLogic: 'AND',
-      rules: [{ fieldPath: 'company.employees', operator: 'gte', value: 50 }],
+      rules: [{ field: 'company.employees', operator: 'gte', value: 50 }],
       matchAction: 'continue',
       noMatchAction: 'exclude',
     },
@@ -214,7 +214,7 @@ const leadFunnel: Funnel = {
       order: 1,
       name: 'High Engagement',
       filterLogic: 'AND',
-      rules: [{ fieldPath: 'engagement_score', operator: 'gte', value: 7 }],
+      rules: [{ field: 'engagement_score', operator: 'gte', value: 7 }],
       matchAction: 'tag_continue',
       noMatchAction: 'continue',
       matchTags: ['high-engagement'],
@@ -225,9 +225,9 @@ const leadFunnel: Funnel = {
       name: 'Target Industries',
       filterLogic: 'OR',
       rules: [
-        { fieldPath: 'company.industry', operator: 'eq', value: 'Technology' },
-        { fieldPath: 'company.industry', operator: 'eq', value: 'SaaS' },
-        { fieldPath: 'company.industry', operator: 'eq', value: 'FinTech' },
+        { field: 'company.industry', operator: 'eq', value: 'Technology' },
+        { field: 'company.industry', operator: 'eq', value: 'SaaS' },
+        { field: 'company.industry', operator: 'eq', value: 'FinTech' },
       ],
       matchAction: 'output',
       noMatchAction: 'exclude',

package/src/components/FunnelStageBuilder/FunnelStageBuilder.stories.tsx

@@ -5,11 +5,11 @@
 import type { Meta, StoryObj } from '@storybook/react';
 import { useState } from 'react';
 import { FunnelStageBuilder } from './FunnelStageBuilder';
-import { Funnel, FieldDefinition } from '../../types';
+import { Funnel, FieldDefinitionInput } from '../../types';
 import './FunnelStageBuilder.css';
 
 // Sample field registry
-const sampleFieldRegistry: FieldDefinition[] = [
+const sampleFieldRegistry: FieldDefinitionInput[] = [
   // Firm fields
   {
     name: 'firm.name',

package/src/components/FunnelStageBuilder/FunnelStageBuilder.test.tsx

@@ -5,10 +5,10 @@
 import { describe, it, expect, vi } from 'vitest';
 import { render, screen, fireEvent, waitFor } from '@testing-library/react';
 import { FunnelStageBuilder } from './FunnelStageBuilder';
-import { Funnel, FieldDefinition } from '../../types';
+import { Funnel, FieldDefinitionInput } from '../../types';
 
 // Mock field registry
-const mockFieldRegistry: FieldDefinition[] = [
+const mockFieldRegistry: FieldDefinitionInput[] = [
   {
     name: 'firm.stage',
     label: 'Firm Stage',

package/src/components/FunnelStageBuilder/FunnelStageBuilder.tsx

@@ -25,7 +25,7 @@ import {
   sortableKeyboardCoordinates,
   verticalListSortingStrategy,
 } from '@dnd-kit/sortable';
-import { Funnel, FunnelStage, FieldDefinition } from '../../types';
+import { Funnel, FunnelStage, FieldDefinitionInput } from '../../types';
 import { StageCard } from './StageCard';
 import { AddStageButton } from './AddStageButton';
 
@@ -37,7 +37,7 @@ export interface FunnelStageBuilderProps {
   onUpdate: (funnel: Funnel) => void;
 
   /** Available fields for filter rules */
-  fieldRegistry: FieldDefinition[];
+  fieldRegistry: FieldDefinitionInput[];
 
   /** Optional CSS class */
   className?: string;

package/src/components/FunnelStageBuilder/StageCard.tsx

@@ -12,7 +12,7 @@
 import React from 'react';
 import { useSortable } from '@dnd-kit/sortable';
 import { CSS } from '@dnd-kit/utilities';
-import { FunnelStage, FieldDefinition } from '../../types';
+import { FunnelStage, FieldDefinitionInput } from '../../types';
 import { StageForm } from './StageForm';
 
 export interface StageCardProps {
@@ -32,7 +32,7 @@ export interface StageCardProps {
   onRemove: () => void;
 
   /** Available fields */
-  fieldRegistry: FieldDefinition[];
+  fieldRegistry: FieldDefinitionInput[];
 
   /** Validation error */
   error?: string;

package/src/components/FunnelStageBuilder/StageForm.tsx

@@ -11,7 +11,7 @@
  */
 
 import React, { useCallback, useState } from 'react';
-import { FunnelStage, FieldDefinition, FilterLogic, MatchAction, NoMatchAction, FilterRule } from '../../types';
+import { FunnelStage, FieldDefinitionInput, FilterLogic, MatchAction, NoMatchAction, FilterRule } from '../../types';
 import { StageActions } from './StageActions';
 import { TagInput } from './TagInput';
 import { FilterRuleEditor } from '../FilterRuleEditor/FilterRuleEditor';
@@ -24,7 +24,7 @@ export interface StageFormProps {
   onUpdate: (stage: FunnelStage) => void;
 
   /** Available fields */
-  fieldRegistry: FieldDefinition[];
+  fieldRegistry: FieldDefinitionInput[];
 }
 
 /**

package/src/core/evaluator.example.ts

@@ -72,7 +72,7 @@ const investors: Investor[] = [
 // Example 1a: Single rule evaluation
 console.log('=== Example 1a: Single Rule ===');
 const rule1: FilterRule = {
-  fieldPath: 'firm.aum',
+  field: 'firm.aum',
   operator: 'gte',
   value: 100000000,
 };
@@ -85,9 +85,9 @@ investors.forEach(investor => {
 // Example 1b: Multiple rules with AND logic
 console.log('\n=== Example 1b: Multiple Rules (AND) ===');
 const rules1: FilterRule[] = [
-  { fieldPath: 'firm.stage', operator: 'in', value: ['Series A', 'Series B'] },
-  { fieldPath: 'firm.aum', operator: 'gte', value: 100000000 },
-  { fieldPath: 'tags', operator: 'has_tag', value: 'qualified' },
+  { field: 'firm.stage', operator: 'in', value: ['Series A', 'Series B'] },
+  { field: 'firm.aum', operator: 'gte', value: 100000000 },
+  { field: 'tags', operator: 'has_tag', value: 'qualified' },
 ];
 
 const qualified = filterEntities(investors, rules1, 'AND');
@@ -151,7 +151,7 @@ const recipes: Recipe[] = [
 // Example 2a: Filter by dietary restrictions
 console.log('\n=== Example 2: Recipe Filtering ===');
 const veganRules: FilterRule[] = [
-  { fieldPath: 'dietary', operator: 'has_tag', value: 'vegan' },
+  { field: 'dietary', operator: 'has_tag', value: 'vegan' },
 ];
 
 const veganRecipes = filterEntities(recipes, veganRules);
@@ -159,9 +159,9 @@ console.log('Vegan recipes:', veganRecipes.map(r => r.name));
 
 // Example 2b: Filter by multiple criteria (quick meals)
 const quickMealRules: FilterRule[] = [
-  { fieldPath: 'prep_time_minutes', operator: 'lte', value: 30 },
-  { fieldPath: 'difficulty', operator: 'in', value: ['easy', 'medium'] },
-  { fieldPath: 'rating', operator: 'gte', value: 4.0 },
+  { field: 'prep_time_minutes', operator: 'lte', value: 30 },
+  { field: 'difficulty', operator: 'in', value: ['easy', 'medium'] },
+  { field: 'rating', operator: 'gte', value: 4.0 },
 ];
 
 const quickMeals = filterEntities(recipes, quickMealRules, 'AND');
@@ -222,9 +222,9 @@ const repos: GitHubRepo[] = [
 // Example 3a: Find popular active repos
 console.log('\n=== Example 3: GitHub Repos ===');
 const popularRepoRules: FilterRule[] = [
-  { fieldPath: 'stars', operator: 'gte', value: 100 },
-  { fieldPath: 'is_archived', operator: 'is_false', value: null },
-  { fieldPath: 'last_updated', operator: 'gte', value: new Date('2024-01-01') },
+  { field: 'stars', operator: 'gte', value: 100 },
+  { field: 'is_archived', operator: 'is_false', value: null },
+  { field: 'last_updated', operator: 'gte', value: new Date('2024-01-01') },
 ];
 
 const popularRepos = filterEntities(repos, popularRepoRules, 'AND');
@@ -232,8 +232,8 @@ console.log('Popular active repos:', popularRepos.map(r => r.name));
 
 // Example 3b: Find TypeScript projects with React
 const tsReactRules: FilterRule[] = [
-  { fieldPath: 'language', operator: 'eq', value: 'TypeScript' },
-  { fieldPath: 'topics', operator: 'has_tag', value: 'react' },
+  { field: 'language', operator: 'eq', value: 'TypeScript' },
+  { field: 'topics', operator: 'has_tag', value: 'react' },
 ];
 
 const tsReactRepos = filterEntities(repos, tsReactRules, 'AND');
@@ -247,7 +247,7 @@ console.log('\n=== Example 4: Advanced Patterns ===');
 
 // Pattern 1: Negation
 const notArchivedRule: FilterRule = {
-  fieldPath: 'is_archived',
+  field: 'is_archived',
   operator: 'is_true',
   value: null,
   negate: true, // Negate the result
@@ -258,7 +258,7 @@ console.log('Active repos (using negate):', activeRepos.map(r => r.name));
 
 // Pattern 2: Complex string matching
 const emailDomainRule: FilterRule = {
-  fieldPath: 'email',
+  field: 'email',
   operator: 'matches',
   value: '@acme\\.vc$', // Matches emails ending with @acme.vc
 };
@@ -268,8 +268,8 @@ console.log('Acme VC investors:', acmeInvestors.map(i => i.name));
 
 // Pattern 3: OR logic (match any condition)
 const flexibleStageRules: FilterRule[] = [
-  { fieldPath: 'firm.stage', operator: 'eq', value: 'Series A' },
-  { fieldPath: 'firm.aum', operator: 'gte', value: 500000000 }, // OR very large fund
+  { field: 'firm.stage', operator: 'eq', value: 'Series A' },
+  { field: 'firm.aum', operator: 'gte', value: 500000000 }, // OR very large fund
 ];
 
 const flexibleMatch = filterEntities(investors, flexibleStageRules, 'OR');
@@ -286,7 +286,7 @@ investorsWithoutEmail.push({
 });
 
 const hasEmailRule: FilterRule = {
-  fieldPath: 'email',
+  field: 'email',
   operator: 'isnotnull',
   value: null,
 };
@@ -296,7 +296,7 @@ console.log('Investors with email:', withEmail.map(i => i.name));
 
 // Pattern 5: Array operations
 const multiGeographyRule: FilterRule = {
-  fieldPath: 'firm.geography',
+  field: 'firm.geography',
   operator: 'has_all',
   value: ['US', 'Europe'],
 };
@@ -329,22 +329,22 @@ function simulateFunnel<T>(entities: T[], stages: Array<{ name: string; rules: F
 const investorFunnelStages = [
   {
     name: 'Active & Not Archived',
-    rules: [{ fieldPath: 'tags', operator: 'has_tag', value: 'active' } as FilterRule],
+    rules: [{ field: 'tags', operator: 'has_tag', value: 'active' } as FilterRule],
     logic: 'AND' as const,
   },
   {
     name: 'Series A+ Stage',
-    rules: [{ fieldPath: 'firm.stage', operator: 'in', value: ['Series A', 'Series B', 'Series C'] } as FilterRule],
+    rules: [{ field: 'firm.stage', operator: 'in', value: ['Series A', 'Series B', 'Series C'] } as FilterRule],
     logic: 'AND' as const,
   },
   {
     name: 'Minimum AUM $100M',
-    rules: [{ fieldPath: 'firm.aum', operator: 'gte', value: 100000000 } as FilterRule],
+    rules: [{ field: 'firm.aum', operator: 'gte', value: 100000000 } as FilterRule],
     logic: 'AND' as const,
   },
   {
     name: 'Qualified Tag',
-    rules: [{ fieldPath: 'tags', operator: 'has_tag', value: 'qualified' } as FilterRule],
+    rules: [{ field: 'tags', operator: 'has_tag', value: 'qualified' } as FilterRule],
     logic: 'AND' as const,
   },
 ];

package/src/core/evaluator.test.ts

@@ -544,10 +544,13 @@ describe('Multiple Rules', () => {
 
 describe('Detailed Results', () => {
   it('should return detailed rule result', () => {
-    const rule: FilterRule = { fieldPath: 'firm.stage', operator: 'eq', value: 'Series A' };
+    const rule: FilterRule = { field: 'firm.stage', operator: 'eq', value: 'Series A' };
     const result = evaluateRuleWithResult(sampleEntity, rule);
 
     expect(result).toEqual({
+      // `field` is the canonical key; `fieldPath` mirrors it for readers
+      // written before the one-contract change (bd startsim-pxzlf).
+      field: 'firm.stage',
       fieldPath: 'firm.stage',
       operator: 'eq',
       value: 'Series A',

package/src/core/evaluator.ts

@@ -11,6 +11,7 @@
  */
 
 import type { FilterRule, RuleResult } from '../types';
+import { ruleField } from '../types';
 import { resolveField } from './field-resolver';
 import { applyOperator } from './operators';
 
@@ -40,8 +41,10 @@ import { applyOperator } from './operators';
  * ```
  */
 export function evaluateRule<T>(entity: T, rule: FilterRule): boolean {
-  // Resolve field value from entity
-  const actualValue = resolveField(entity, rule.fieldPath);
+  // Resolve field value from entity. `ruleField` reads the canonical `field`
+  // and falls back to the deprecated `fieldPath`, so a rule persisted under
+  // either shape evaluates the same.
+  const actualValue = resolveField(entity, ruleField(rule));
 
   // Apply operator
   const result = applyOperator(rule.operator, actualValue, rule.value);
@@ -77,9 +80,10 @@ export function evaluateRuleWithResult<T>(
   entity: T,
   rule: FilterRule
 ): RuleResult {
+  const field = ruleField(rule);
   try {
     // Resolve field value
-    const actualValue = resolveField(entity, rule.fieldPath);
+    const actualValue = resolveField(entity, field);
 
     // Apply operator
     const operatorResult = applyOperator(rule.operator, actualValue, rule.value);
@@ -88,7 +92,8 @@ export function evaluateRuleWithResult<T>(
     const matched = rule.negate ? !operatorResult : operatorResult;
 
     return {
-      fieldPath: rule.fieldPath,
+      field,
+      fieldPath: field,
       operator: rule.operator,
       value: rule.value,
       actualValue: actualValue,
@@ -97,7 +102,8 @@ export function evaluateRuleWithResult<T>(
   } catch (error) {
     // Handle evaluation errors gracefully
     return {
-      fieldPath: rule.fieldPath,
+      field,
+      fieldPath: field,
       operator: rule.operator,
       value: rule.value,
       actualValue: undefined,

package/src/core/operators.ts

@@ -46,6 +46,28 @@ export function applyOperator(
     case 'lte':
       return compareValues(actual, expected, (a, e) => a <= e);
 
+    // Inclusive range. The backend's ValueShape.TUPLE2: value is [min, max].
+    case 'between': {
+      if (!Array.isArray(expected) || expected.length !== 2) return false;
+      const [min, max] = expected;
+      return (
+        compareValues(actual, min, (a, e) => a >= e) &&
+        compareValues(actual, max, (a, e) => a <= e)
+      );
+    }
+
+    // ========================================================================
+    // Presence — the backend spelling. A tag category with no value, an
+    // attribute that is simply set. Absent, null and '' all count as absent,
+    // because a tag row that does not exist and an empty one mean the same
+    // thing to a person building a funnel.
+    // ========================================================================
+    case 'exists':
+      return isPresent(actual);
+
+    case 'not_exists':
+      return !isPresent(actual);
+
     // ========================================================================
     // String operations (case-insensitive)
     // ========================================================================
@@ -148,6 +170,19 @@ export function applyOperator(
   }
 }
 
+/**
+ * Whether a resolved value counts as present for exists / not_exists.
+ *
+ * An empty array is absent: 'tag.stage_focus' resolving to [] means the entity
+ * carries no tag in that category, which is exactly what not_exists asks about.
+ */
+function isPresent(actual: any): boolean {
+  if (actual === null || actual === undefined) return false;
+  if (typeof actual === 'string') return actual.length > 0;
+  if (Array.isArray(actual)) return actual.length > 0;
+  return true;
+}
+
 /**
  * Compare values with type normalization
  *

package/src/store/create-funnel-store.ts

@@ -204,6 +204,7 @@ export function createFunnelStore<TEntity = any>(
         name: `${funnel.name} (Copy)`,
         description: funnel.description,
         status: 'draft', // Always create as draft
+        entityType: funnel.entityType,
         inputType: funnel.inputType,
         stages: funnel.stages.map((stage, index) => ({
           ...stage,

package/src/stories/demo-data/investors.ts

@@ -1,6 +1,6 @@
-import type { FieldDefinition } from '../../types';
+import type { FieldDefinitionInput } from '../../types';
 
-export const investorFields: FieldDefinition[] = [
+export const investorFields: FieldDefinitionInput[] = [
   {
     name: 'firm.name',
     type: 'text',

package/src/stories/demo-data/leads.ts

@@ -1,6 +1,6 @@
-import type { FieldDefinition } from '../../types';
+import type { FieldDefinitionInput } from '../../types';
 
-export const leadFields: FieldDefinition[] = [
+export const leadFields: FieldDefinitionInput[] = [
   {
     name: 'lead.name',
     type: 'text',

package/src/stories/demo-data/recipes.ts

@@ -1,6 +1,6 @@
-import type { FieldDefinition } from '../../types';
+import type { FieldDefinitionInput } from '../../types';
 
-export const recipeFields: FieldDefinition[] = [
+export const recipeFields: FieldDefinitionInput[] = [
   {
     name: 'recipe.name',
     type: 'text',