@startsimpli/funnels 0.4.13 → 0.4.15

package/src/page/index.ts

@@ -0,0 +1,24 @@
+/**
+ * @startsimpli/funnels/page — the whole Funnels screen, mounted not rebuilt.
+ *
+ * A SUBPATH AND NOT THE ROOT BARREL, deliberately (the same reasoning
+ * `@startsimpli/ui/foundry` writes down for itself). This module is the one
+ * thing in the package that needs `@startsimpli/ui` — for UnifiedTable, and so
+ * for repo rule #8's server-side paging. raise and market import
+ * `@startsimpli/funnels` for the engine and the rule editor and must not be
+ * made to install a UI library to get them, so the import lives behind
+ *
+ *     import { FunnelsPage } from '@startsimpli/funnels/page'
+ *
+ * and `@startsimpli/ui` is an OPTIONAL peer dependency.
+ *
+ * bd startsim-em5mn.
+ */
+export { FunnelsPage } from './FunnelsPage';
+export type {
+  FunnelsPageProps,
+  FunnelListRow,
+  FunnelResultRow,
+  FunnelListQuery,
+  StageReached,
+} from './types';

package/src/page/types.ts

@@ -0,0 +1,102 @@
+/**
+ * What the FunnelsPage composer is handed, and the row shapes it renders.
+ *
+ * The wire shapes below are DECLARED HERE rather than in `../types` on purpose.
+ * `../types` is the funnel CONTRACT — the shapes paired with
+ * `@startsimpli/api`'s by `contract.test.ts`, changed only in lockstep. What a
+ * LIST endpoint adds on top (`stage_count`, `total_runs`, `last_run_*`) and
+ * what `FunnelResultSerializer` emits per row are presentation payloads: this
+ * page is their only reader, so widening the contract for them would make two
+ * packages agree about something neither of them models.
+ *
+ * bd startsim-em5mn.
+ */
+import type { FunnelApiClient } from '../api/client';
+import type { Funnel, FunnelStatus } from '../types';
+
+/**
+ * A funnel as a LIST answers it: the contract shape plus the rollups
+ * `FunnelSerializer` computes (`stage_count`, `total_runs`, `last_run_at`,
+ * `last_run_id`, `last_run_matched`, `created_by_name`), camelized by the
+ * adapter.
+ */
+export interface FunnelListRow extends Funnel {
+  stageCount?: number;
+  totalRuns?: number;
+  lastRunAt?: string | null;
+  lastRunId?: string | null;
+  lastRunMatched?: number | null;
+  createdByName?: string | null;
+}
+
+/** Where a result stopped, named from what the run RECORDED (breakdown.py). */
+export interface StageReached {
+  id: string;
+  name: string | null;
+  order: number | null;
+}
+
+/**
+ * One row of a run's results, as the control plane serves them.
+ *
+ * `context` is free-form and reaches the browser through an adapter that
+ * camelizes KEYS, so it is rendered as an opaque count rather than as fields:
+ * a key the executor wrote as `reached_stage_id` arrives as `reachedStageId`,
+ * and presenting that as though it were the stored name would be a lie about
+ * the record. `stageReached` is the answer to the same question, computed
+ * server-side, and is what this page reads.
+ */
+export interface FunnelResultRow {
+  id: string;
+  entityId: string;
+  entityType: string;
+  matched: boolean;
+  excludedAtStage: string | null;
+  stageReached: StageReached | null;
+  exclusionReason?: string;
+  context?: Record<string, unknown>;
+  accumulatedTags?: string[];
+  createdAt: string;
+}
+
+/** The server-side narrowings the funnel list supports. */
+export interface FunnelListQuery {
+  status: FunnelStatus | '';
+  search: string;
+  page: number;
+}
+
+export interface FunnelsPageProps {
+  /**
+   * The funnel client, already bound to the path family of the surface that is
+   * mounting this page — `foundryTenantFunnelPaths(slug)` on the control plane,
+   * `proxiedCentralFunnelPaths('/central-api')` inside a fork. The page never
+   * builds a URL of its own; that is the whole point of the injection.
+   */
+  client: FunnelApiClient;
+
+  /**
+   * Where the rule vocabulary comes from. SEPARATE FROM `client` because the
+   * two are not on the same surface: `/fields/` is mounted ONLY on central
+   * (`/api/v1/funnels/fields/`, scoped to the caller's company), and the
+   * control plane's `funnels/fields/` is shadowed by its `funnels/<id>/`
+   * action and 404s. See the note on `foundryTenantFunnelPaths`.
+   *
+   * Defaults to `client`, which is right for any surface that does serve the
+   * endpoint under its own prefix.
+   */
+  fieldsClient?: FunnelApiClient;
+
+  /**
+   * Whether this viewer may create, edit and run funnels (`manage_funnels`).
+   * Read-only viewers (`view_funnels`) still get the list, the history and the
+   * results. The server enforces this either way — this only keeps the page
+   * from offering a button that will 403.
+   */
+  canManage?: boolean;
+
+  /** Rows per page for both tables. */
+  pageSize?: number;
+
+  className?: string;
+}

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',

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');
+  });
+});