@startsimpli/funnels 0.4.13 → 0.4.14

package/src/types/contract.test.ts

@@ -0,0 +1,284 @@
+/**
+ * The one funnel contract (bd startsim-pxzlf).
+ *
+ * Three shapes shipped before this: this package's flat {fieldPath} rule,
+ * @startsimpli/api's own rule type, and raise's colon-encoded field names. The
+ * canonical one is the backend's: FunnelFilterRule.field carries a REGISTRY KEY
+ * ('contact.name', 'tag.<category>', 'metric.<type>.<subtype>', 'profile.<type>',
+ * 'icp.<signal>'), and GET /api/v1/funnels/fields/ describes those keys.
+ *
+ * These tests pin the canonical shape AND the tolerance that keeps the two live
+ * consumers working: a rule that still carries only `fieldPath`, and a field
+ * registry still written as {name,type,operators}, must keep evaluating and
+ * rendering.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  fieldKey,
+  fieldOperators,
+  fieldValueType,
+  isFieldDefinition,
+  isFilterRule,
+  isRuleGroup,
+  normalizeFieldDefinition,
+  normalizeRule,
+  ruleField,
+  ruleLeaves,
+  validateFilterRule,
+  getValidOperators,
+} from './index';
+import type {
+  FieldDefinition,
+  FieldDefinitionInput,
+  FilterRule,
+  FunnelStage,
+  Funnel,
+  RuleGroup,
+} from './index';
+import { evaluateRule } from '../core/evaluator';
+
+describe('FilterRule.field — the canonical registry key', () => {
+  it('carries the registry key the backend resolves', () => {
+    const rule: FilterRule = { field: 'tag.stage_focus', operator: 'eq', value: 'seed' };
+    expect(ruleField(rule)).toBe('tag.stage_focus');
+    expect(isFilterRule(rule)).toBe(true);
+    expect(validateFilterRule(rule)).toEqual([]);
+  });
+
+  it('still reads a rule that only carries the deprecated fieldPath', () => {
+    const legacy = { fieldPath: 'firm.stage', operator: 'eq', value: 'Series A' } as FilterRule;
+    expect(ruleField(legacy)).toBe('firm.stage');
+    expect(isFilterRule(legacy)).toBe(true);
+    expect(validateFilterRule(legacy)).toEqual([]);
+  });
+
+  it('prefers field over fieldPath when a row carries both — the auto-migrated row', () => {
+    // Not hypothetical: the serializer's legacy branch sets attrs['field'] and
+    // leaves field_path alone, and _create_rule_tree persists the whole dict.
+    // Every rule saved through that branch comes back carrying both.
+    const both = {
+      field: 'contact.name',
+      fieldPath: 'contact__name',
+      operator: 'eq',
+      value: 'Ada',
+    } as FilterRule;
+    expect(ruleField(both)).toBe('contact.name');
+  });
+
+  it('reports a rule that names no field at all', () => {
+    const errors = validateFilterRule({ operator: 'eq', value: 1 } as unknown as FilterRule);
+    expect(errors.some((e) => /field/i.test(e))).toBe(true);
+  });
+
+  it('evaluates locally off `field`, not just fieldPath', () => {
+    const entity = { firm: { stage: 'Series A' } };
+    expect(evaluateRule(entity, { field: 'firm.stage', operator: 'eq', value: 'Series A' })).toBe(
+      true
+    );
+    expect(
+      evaluateRule(entity, { fieldPath: 'firm.stage', operator: 'eq', value: 'Seed' } as FilterRule)
+    ).toBe(false);
+  });
+
+  it('normalizeRule lifts a legacy or snake_case wire rule onto the canonical shape', () => {
+    expect(normalizeRule({ fieldPath: 'contact.email', operator: 'eq', value: 'a@b.c' })).toEqual({
+      field: 'contact.email',
+      operator: 'eq',
+      value: 'a@b.c',
+    });
+    // A row the backend auto-migrated keeps its legacy key; normalizing drops
+    // the deprecated one and keeps the canonical.
+    expect(
+      normalizeRule({
+        field: 'contact.name',
+        fieldPath: 'contact__name',
+        operator: 'contains',
+        value: 'Ada',
+      })
+    ).toEqual({ field: 'contact.name', operator: 'contains', value: 'Ada' });
+
+    // An adapter that does not camelize leaves group_logic snake_cased.
+    const group = normalizeRule({
+      group_logic: 'any',
+      children: [{ field: 'contact.name', operator: 'eq', value: 'Ada' }],
+    });
+    expect(isRuleGroup(group)).toBe(true);
+  });
+});
+
+describe('the operator vocabulary matches the backend registry', () => {
+  it('includes between / exists / not_exists (resolvers/base.py Operator)', () => {
+    const rules: FilterRule[] = [
+      { field: 'metric.financial.check_size_min', operator: 'between', value: [1, 10] },
+      { field: 'tag.stage_focus', operator: 'exists', value: null },
+      { field: 'tag.stage_focus', operator: 'not_exists', value: null },
+    ];
+    for (const rule of rules) expect(validateFilterRule(rule)).toEqual([]);
+  });
+
+  it('evaluates them locally', () => {
+    expect(
+      evaluateRule({ n: 5 }, { field: 'n', operator: 'between', value: [1, 10] })
+    ).toBe(true);
+    expect(evaluateRule({ n: 50 }, { field: 'n', operator: 'between', value: [1, 10] })).toBe(
+      false
+    );
+    expect(evaluateRule({ n: 5 }, { field: 'n', operator: 'exists', value: null })).toBe(true);
+    expect(evaluateRule({}, { field: 'n', operator: 'exists', value: null })).toBe(false);
+    expect(evaluateRule({}, { field: 'n', operator: 'not_exists', value: null })).toBe(true);
+  });
+
+  it('does not demand a value for the operators that take none', () => {
+    expect(validateFilterRule({ field: 'tag.x', operator: 'exists' } as FilterRule)).toEqual([]);
+    expect(validateFilterRule({ field: 'tag.x', operator: 'not_exists' } as FilterRule)).toEqual(
+      []
+    );
+  });
+
+  it('offers between for numbers and dates', () => {
+    expect(getValidOperators('number')).toContain('between');
+    expect(getValidOperators('date')).toContain('between');
+  });
+
+  it('offers exists / not_exists for an enum field, the shape a tag category has', () => {
+    expect(getValidOperators('enum')).toEqual(
+      expect.arrayContaining(['eq', 'ne', 'in', 'not_in', 'exists', 'not_exists'])
+    );
+  });
+});
+
+describe('FieldDefinition is shaped like the /fields/ payload', () => {
+  const fromBackend: FieldDefinition = {
+    key: 'tag.stage_focus',
+    label: 'stage_focus',
+    category: 'Tags',
+    valueType: 'enum',
+    enumValues: ['pre_seed', 'seed', 'series_a'],
+    allowedOperators: ['eq', 'ne', 'in', 'not_in', 'exists', 'not_exists'],
+  };
+
+  it('accepts the payload verbatim', () => {
+    expect(isFieldDefinition(fromBackend)).toBe(true);
+    expect(fieldKey(fromBackend)).toBe('tag.stage_focus');
+    expect(fieldValueType(fromBackend)).toBe('enum');
+    expect(fieldOperators(fromBackend)).toContain('not_exists');
+  });
+
+  it('accepts a registry still written the old way — {name,type,operators}', () => {
+    const legacy: FieldDefinitionInput = {
+      name: 'contact__name',
+      label: 'Name',
+      type: 'string',
+      operators: ['eq', 'contains'],
+    };
+    expect(isFieldDefinition(legacy)).toBe(true);
+    expect(fieldKey(legacy)).toBe('contact__name');
+    expect(fieldValueType(legacy)).toBe('string');
+    expect(fieldOperators(legacy)).toEqual(['eq', 'contains']);
+  });
+
+  it('accepts the raw snake_case payload, for an adapter that does not camelize', () => {
+    const wire: FieldDefinitionInput = {
+      key: 'metric.financial.check_size_min',
+      label: 'check_size_min',
+      category: 'Financial',
+      value_type: 'number',
+      enum_values: [],
+      allowed_operators: ['gte', 'lte', 'between'],
+    };
+    const normalized = normalizeFieldDefinition(wire);
+    expect(normalized.key).toBe('metric.financial.check_size_min');
+    expect(normalized.valueType).toBe('number');
+    expect(normalized.allowedOperators).toEqual(['gte', 'lte', 'between']);
+    expect(normalized.enumValues).toEqual([]);
+  });
+
+  it('normalizes a legacy definition onto the canonical keys without losing anything', () => {
+    const normalized = normalizeFieldDefinition({
+      name: 'contact__email',
+      label: 'Email',
+      type: 'string',
+      operators: ['eq'],
+      category: 'Contact',
+    });
+    expect(normalized).toMatchObject({
+      key: 'contact__email',
+      label: 'Email',
+      valueType: 'string',
+      allowedOperators: ['eq'],
+      category: 'Contact',
+    });
+  });
+
+  it('turns an enum definition into choices the value inputs can render', () => {
+    const normalized = normalizeFieldDefinition(fromBackend);
+    expect(normalized.constraints?.choices).toEqual(['pre_seed', 'seed', 'series_a']);
+  });
+});
+
+describe('entityType is a string, not a two-value union', () => {
+  it('takes any entity type the backend models', () => {
+    // Funnel.entity_type is a CharField with no choices: 'investor', 'recipe',
+    // 'lead', a foundry's own type — 'contact' | 'organization' was a guess.
+    const funnel: Funnel = {
+      id: 'f1',
+      name: 'Artists in reach',
+      status: 'active',
+      entityType: 'sc_artist',
+      stages: [],
+      createdAt: '2026-09-16T00:00:00Z',
+      updatedAt: '2026-09-16T00:00:00Z',
+    };
+    expect(funnel.entityType).toBe('sc_artist');
+  });
+});
+
+describe('rule groups', () => {
+  const group: RuleGroup = {
+    groupLogic: 'any',
+    children: [
+      { field: 'tag.stage_focus', operator: 'eq', value: 'seed' },
+      {
+        groupLogic: 'all',
+        children: [
+          { field: 'metric.financial.check_size_min', operator: 'gte', value: 100000 },
+          { field: 'contact.location', operator: 'contains', value: 'SF' },
+        ],
+      },
+    ],
+  };
+
+  it('tells a group from a leaf', () => {
+    expect(isRuleGroup(group)).toBe(true);
+    expect(isRuleGroup({ field: 'contact.name', operator: 'eq', value: 'Ada' })).toBe(false);
+  });
+
+  it('flattens a tree to its leaves in document order', () => {
+    expect(ruleLeaves([group]).map(ruleField)).toEqual([
+      'tag.stage_focus',
+      'metric.financial.check_size_min',
+      'contact.location',
+    ]);
+  });
+
+  it('leaves a flat list alone', () => {
+    const flat: FilterRule[] = [{ field: 'contact.name', operator: 'eq', value: 'Ada' }];
+    expect(ruleLeaves(flat)).toEqual(flat);
+  });
+});
+
+describe('a stage still carries its flat leaves', () => {
+  it('keeps rules[] as leaves so every existing consumer keeps reading it', () => {
+    const stage: FunnelStage = {
+      id: 's1',
+      order: 0,
+      name: 'Qualified',
+      filterLogic: 'AND',
+      rules: [{ field: 'contact.email', operator: 'exists', value: null }],
+      matchAction: 'continue',
+      noMatchAction: 'exclude',
+    };
+    expect(ruleField(stage.rules[0])).toBe('contact.email');
+  });
+});