@startsimpli/funnels 0.4.13 → 0.4.14

package/src/types/index.ts

@@ -16,6 +16,13 @@
 
 /**
  * Filter operators - works with any data type
+ *
+ * The vocabulary is the backend's: backend/apps/funnels/resolvers/base.py
+ * declares eq/ne/in/not_in/gt/lt/gte/lte/between/contains/startswith/endswith/
+ * exists/not_exists, and a rule whose operator is outside a field resolver's
+ * `allowed_operators` is rejected at POST time. The extra members below
+ * (matches, has_any, is_true, …) are client-side evaluation sugar with no
+ * server resolver — the local engine understands them, the API will not.
  */
 export type Operator =
   // Equality
@@ -27,6 +34,7 @@ export type Operator =
   | 'lt'              // Less than
   | 'gte'             // Greater than or equal
   | 'lte'             // Less than or equal
+  | 'between'         // Within [min, max] (inclusive)
 
   // String operations
   | 'contains'        // String contains substring
@@ -41,7 +49,11 @@ export type Operator =
   | 'has_any'         // Array has any of these values
   | 'has_all'         // Array has all of these values
 
-  // Null checks
+  // Presence (the backend spelling)
+  | 'exists'          // Field/tag category is present
+  | 'not_exists'      // Field/tag category is absent
+
+  // Null checks (client-side aliases of exists/not_exists)
   | 'isnull'          // Field is null/undefined
   | 'isnotnull'       // Field is not null/undefined
 
@@ -55,11 +67,15 @@ export type Operator =
 
 /**
  * Field data types - for operator validation
+ *
+ * 'string' | 'number' | 'boolean' | 'enum' | 'date' are what the backend field
+ * registry emits as `value_type`. The rest are client-side evaluation types.
  */
 export type FieldType =
   | 'string'
   | 'number'
   | 'boolean'
+  | 'enum'
   | 'date'
   | 'array'
   | 'object'
@@ -71,20 +87,36 @@ export type FieldType =
 // ============================================================================
 
 /**
- * A single filter rule
+ * A single (leaf) filter rule
+ *
+ * `field` is the CANONICAL key — the same key the backend resolves through
+ * backend/apps/funnels/resolvers/registry.py, and the same key
+ * GET /api/v1/funnels/fields/ describes:
  *
- * Examples:
- * - { fieldPath: 'firm.stage', operator: 'eq', value: 'Series A' }
- * - { fieldPath: 'recipe.cuisine', operator: 'in', value: ['Italian', 'French'] }
- * - { fieldPath: 'contact.email', operator: 'isnotnull', value: null }
- * - { fieldPath: 'organization.tags', operator: 'has_tag', value: 'enterprise' }
+ * - { field: 'contact.name',                       operator: 'contains', value: 'Ada' }
+ * - { field: 'tag.stage_focus',                    operator: 'eq',       value: 'seed' }
+ * - { field: 'tag.stage_focus',                    operator: 'exists' }
+ * - { field: 'metric.financial.check_size_min',    operator: 'between',  value: [1e5, 5e5] }
+ * - { field: 'profile.vc',                         operator: 'exists' }
+ * - { field: 'icp.has_frontend_stack',             operator: 'eq',       value: true }
+ *
+ * For purely client-side evaluation the key doubles as a dot-notation path into
+ * the entity ('firm.stage'), which is what the local engine resolves.
  */
 export interface FilterRule {
   /**
-   * Dot-notation path to field
-   * Examples: 'name', 'firm.stage', 'profile.linkedin_url', 'tags', 'metrics.arr_usd'
+   * The registry key this rule filters on.
+   *
+   * Also read as a dot-notation path by the local evaluator, so an in-browser
+   * preview over plain objects works with the same rule the server runs.
    */
-  fieldPath: string;
+  field: string;
+
+  /**
+   * @deprecated Use `field`. Kept so rows persisted under the old shape keep
+   * evaluating and rendering; every reader goes through `ruleField(rule)`.
+   */
+  fieldPath?: string;
 
   /** Comparison operator */
   operator: Operator;
@@ -95,18 +127,51 @@ export interface FilterRule {
    * - eq/ne/gt/lt/gte/lte: any primitive
    * - contains/startswith/endswith: string
    * - in/not_in: array
-   * - isnull/isnotnull: null (value ignored)
+   * - between: [min, max]
+   * - exists/not_exists/isnull/isnotnull: omitted (value ignored)
    * - has_tag/not_has_tag: string (tag name)
    */
-  value: any;
+  value?: any;
 
   /**
    * Optional: negate the rule result
    * Default: false
    */
   negate?: boolean;
+
+  /** Server-assigned id, when the rule came back from the API. */
+  id?: string | number;
+
+  /** Position within its parent list. Assigned by the API. */
+  order?: number;
 }
 
+/**
+ * How a group combines its children. Mirrors
+ * FunnelFilterRule.GroupLogic on the backend ('leaf' is a leaf rule, i.e. a
+ * FilterRule, and never appears on a group).
+ */
+export type GroupLogic = 'all' | 'any' | 'not';
+
+/**
+ * A group of rules — the recursive half of the backend's rule tree.
+ *
+ * The API accepts and emits these nested under a stage's `rules`. Nothing in
+ * this package's local engine evaluates a tree yet (a stage evaluates its flat
+ * leaves under `filterLogic`); the type exists so a client, a composer or a
+ * converter can carry a tree without inventing its own shape — which is
+ * exactly what raise had to do.
+ */
+export interface RuleGroup {
+  groupLogic: GroupLogic;
+  children: FilterRuleNode[];
+  id?: string | number;
+  order?: number;
+}
+
+/** A node of the rule tree: a leaf rule or a group of them. */
+export type FilterRuleNode = FilterRule | RuleGroup;
+
 /**
  * Filter logic for combining rules
  */
@@ -200,9 +265,21 @@ export type FunnelStatus = 'draft' | 'active' | 'paused' | 'archived';
 
 /**
  * Input entity types
+ *
+ * @deprecated Use `Funnel.entityType`. `input_type` is the backend's own
+ * deprecated column (models.py: "DEPRECATED: Use entity_type instead").
  */
 export type InputType = 'contacts' | 'organizations' | 'both' | 'any';
 
+/**
+ * The kind of entity a funnel runs over.
+ *
+ * A STRING, deliberately: Funnel.entity_type is a CharField with no choices, so
+ * 'contact' | 'organization' was never the real set — 'investor', 'recipe',
+ * 'lead', 'sc_artist' and whatever a foundry models are all legitimate.
+ */
+export type EntityType = string;
+
 /**
  * A complete funnel definition
  *
@@ -222,10 +299,19 @@ export interface Funnel<TEntity = any> {
   status: FunnelStatus;
 
   /**
-   * Type of entities this funnel processes
-   * Used for field registry lookup
+   * Type of entities this funnel processes.
+   * Used for field registry lookup (GET …/funnels/fields/?entity_type=…).
+   */
+  entityType: EntityType;
+
+  /**
+   * @deprecated Use `entityType`. The backend keeps `input_type` only for the
+   * transition window.
    */
-  inputType: InputType;
+  inputType?: InputType;
+
+  /** Generic scoping tags: ['fundraise:<uuid>', 'product:raise-simpli']. */
+  tags?: string[];
 
   /** Ordered stages */
   stages: FunnelStage<TEntity>[];
@@ -427,7 +513,10 @@ export interface StageResult {
  * Result for a single rule evaluation
  */
 export interface RuleResult {
-  /** Rule field path */
+  /** The registry key the rule filtered on */
+  field: string;
+
+  /** @deprecated Mirror of `field`, for readers written before the contract. */
   fieldPath: string;
 
   /** Rule operator */
@@ -478,25 +567,45 @@ export interface FieldConstraints {
 /**
  * Field definition in registry
  *
- * Describes what fields are available for filtering
- * on a given entity type
+ * SHAPED LIKE THE BACKEND PAYLOAD. GET /api/v1/funnels/fields/ returns
+ * { key, label, category, value_type, enum_values, allowed_operators } per
+ * entry (backend/apps/funnels/resolvers/registry.py `_resolver_to_dict`), and
+ * that — not a hand-written per-app list — is what should drive a field picker.
+ *
+ * The deprecated `name` / `type` / `operators` trio is still accepted so the
+ * hand-written registries that predate the endpoint (raise's INVESTOR_FIELDS,
+ * market's LEAD_FIELDS) keep rendering. Read through `fieldKey()`,
+ * `fieldValueType()` and `fieldOperators()`, or normalize once with
+ * `normalizeFieldDefinition()`.
  */
 export interface FieldDefinition {
-  /** Unique field identifier (dot-notation path) */
-  name: string;
+  /** The registry key: 'contact.name', 'tag.stage_focus', 'metric.<type>.<subtype>'. */
+  key: string;
 
   /** Human-readable label */
   label: string;
 
-  /** Field data type */
-  type: FieldType;
+  /** Value type, as the registry reports it */
+  valueType: FieldType;
+
+  /** Operators this field accepts — the server rejects anything else */
+  allowedOperators: ValidOperators;
 
-  /** Valid operators for this field */
-  operators: ValidOperators;
+  /** Allowed values, for an enum field (a tag category's known tags) */
+  enumValues?: string[];
 
   /** Field category (for UI grouping) */
   category?: string;
 
+  /** @deprecated Use `key`. */
+  name?: string;
+
+  /** @deprecated Use `valueType`. */
+  type?: FieldType;
+
+  /** @deprecated Use `allowedOperators`. */
+  operators?: ValidOperators;
+
   /** Optional description */
   description?: string;
 
@@ -516,14 +625,41 @@ export interface FieldDefinition {
   relatedFields?: string[];
 }
 
+/**
+ * Anything a caller may hand us as a field definition: the canonical shape, a
+ * legacy {name,type,operators} entry, or the raw snake_case payload from an
+ * adapter that does not camelize. `normalizeFieldDefinition` collapses all
+ * three onto `FieldDefinition`.
+ */
+export interface FieldDefinitionInput {
+  key?: string;
+  name?: string;
+  label?: string;
+  category?: string;
+  valueType?: FieldType;
+  type?: FieldType;
+  value_type?: FieldType;
+  allowedOperators?: ValidOperators;
+  operators?: ValidOperators;
+  allowed_operators?: ValidOperators;
+  enumValues?: string[];
+  enum_values?: string[];
+  description?: string;
+  constraints?: FieldConstraints;
+  sortable?: boolean;
+  searchable?: boolean;
+  examples?: any[];
+  relatedFields?: string[];
+}
+
 /**
  * Field registry for an entity type
  *
  * Maps field paths to their definitions
  */
 export interface FieldRegistry {
-  /** Entity type this registry is for */
-  entityType: string;
+  /** Entity type this registry is for (null when unfiltered) */
+  entityType: EntityType | null;
 
   /** Available fields */
   fields: FieldDefinition[];
@@ -638,9 +774,24 @@ export function isFilterRule(value: unknown): value is FilterRule {
   return (
     typeof r === 'object' &&
     r !== null &&
-    typeof r.fieldPath === 'string' &&
-    typeof r.operator === 'string' &&
-    r.value !== undefined
+    !isRuleGroup(value) &&
+    (typeof r.field === 'string' || typeof r.fieldPath === 'string') &&
+    typeof r.operator === 'string'
+  );
+}
+
+/**
+ * Type guard: is this node a group rather than a leaf?
+ *
+ * Tolerates the snake_case `group_logic` an adapter that does not camelize
+ * leaves on the wire.
+ */
+export function isRuleGroup(value: unknown): value is RuleGroup {
+  if (typeof value !== 'object' || value === null) return false;
+  const node = value as RuleGroup & { group_logic?: string };
+  const logic = node.groupLogic ?? node.group_logic;
+  return (
+    (logic === 'all' || logic === 'any' || logic === 'not') && Array.isArray(node.children)
   );
 }
 
@@ -678,17 +829,132 @@ export function isFunnelResult<TEntity = any>(
  * Type guard: is value a valid FieldDefinition?
  */
 export function isFieldDefinition(value: unknown): value is FieldDefinition {
-  const f = value as FieldDefinition;
+  if (typeof value !== 'object' || value === null) return false;
+  const f = value as FieldDefinitionInput;
+  const key = f.key ?? f.name;
+  const valueType = f.valueType ?? f.type ?? f.value_type;
+  const operators = f.allowedOperators ?? f.operators ?? f.allowed_operators;
   return (
-    typeof f === 'object' &&
-    f !== null &&
-    typeof f.name === 'string' &&
+    typeof key === 'string' &&
     typeof f.label === 'string' &&
-    typeof f.type === 'string' &&
-    Array.isArray(f.operators)
+    typeof valueType === 'string' &&
+    Array.isArray(operators)
   );
 }
 
+// ============================================================================
+// Canonical Accessors
+// ============================================================================
+
+/**
+ * The key a rule filters on.
+ *
+ * ONE reader for the whole package, so a row persisted before the contract
+ * landed (only `fieldPath`) and a row from the current API (`field`) resolve
+ * the same way. `field` wins when both are present.
+ */
+export function ruleField(rule: Pick<FilterRule, 'field' | 'fieldPath'>): string {
+  return rule.field || rule.fieldPath || '';
+}
+
+/** The registry key of a field definition, whichever shape it arrived in. */
+export function fieldKey(field: FieldDefinitionInput): string {
+  return field.key ?? field.name ?? '';
+}
+
+/** The value type of a field definition, whichever shape it arrived in. */
+export function fieldValueType(field: FieldDefinitionInput): FieldType {
+  return field.valueType ?? field.type ?? field.value_type ?? 'any';
+}
+
+/** The operators a field accepts, whichever shape it arrived in. */
+export function fieldOperators(field: FieldDefinitionInput): ValidOperators {
+  return field.allowedOperators ?? field.operators ?? field.allowed_operators ?? [];
+}
+
+/** The enum values of a field definition, whichever shape it arrived in. */
+export function fieldEnumValues(field: FieldDefinitionInput): string[] | undefined {
+  return field.enumValues ?? field.enum_values;
+}
+
+/**
+ * Collapse any accepted field-definition shape onto the canonical one.
+ *
+ * An enum field's values also become `constraints.choices`, so the existing
+ * value inputs render a picker for a tag category without knowing about the
+ * registry endpoint.
+ */
+export function normalizeFieldDefinition(field: FieldDefinitionInput): FieldDefinition {
+  const enumValues = fieldEnumValues(field);
+  const constraints = field.constraints;
+  const normalized: FieldDefinition = {
+    key: fieldKey(field),
+    label: field.label ?? fieldKey(field),
+    valueType: fieldValueType(field),
+    allowedOperators: fieldOperators(field),
+  };
+  if (field.category !== undefined) normalized.category = field.category;
+  if (enumValues !== undefined) normalized.enumValues = enumValues;
+  if (field.description !== undefined) normalized.description = field.description;
+  if (field.sortable !== undefined) normalized.sortable = field.sortable;
+  if (field.searchable !== undefined) normalized.searchable = field.searchable;
+  if (field.examples !== undefined) normalized.examples = field.examples;
+  if (field.relatedFields !== undefined) normalized.relatedFields = field.relatedFields;
+
+  if (constraints || (enumValues && enumValues.length > 0)) {
+    normalized.constraints = {
+      ...(constraints ?? {}),
+      ...(constraints?.choices === undefined && enumValues && enumValues.length > 0
+        ? { choices: [...enumValues] }
+        : {}),
+    };
+  }
+  return normalized;
+}
+
+/** Normalize a whole registry in one call. */
+export function normalizeFieldRegistry(fields: FieldDefinitionInput[]): FieldDefinition[] {
+  return fields.map(normalizeFieldDefinition);
+}
+
+/**
+ * Collapse a rule node from the wire onto the canonical shape: `fieldPath` is
+ * lifted to `field`, `group_logic` to `groupLogic`, recursively.
+ */
+export function normalizeRule(node: unknown): FilterRuleNode {
+  if (isRuleGroup(node)) {
+    const group = node as RuleGroup & { group_logic?: GroupLogic };
+    const normalized: RuleGroup = {
+      groupLogic: (group.groupLogic ?? group.group_logic) as GroupLogic,
+      children: (group.children ?? []).map(normalizeRule),
+    };
+    if (group.id !== undefined) normalized.id = group.id;
+    if (group.order !== undefined) normalized.order = group.order;
+    return normalized;
+  }
+
+  const rule = (node ?? {}) as FilterRule & { field_path?: string };
+  const normalized: FilterRule = {
+    field: rule.field || rule.fieldPath || rule.field_path || '',
+    operator: rule.operator,
+  };
+  if (rule.value !== undefined) normalized.value = rule.value;
+  if (rule.negate !== undefined) normalized.negate = rule.negate;
+  if (rule.id !== undefined) normalized.id = rule.id;
+  if (rule.order !== undefined) normalized.order = rule.order;
+  return normalized;
+}
+
+/** Every leaf of a rule tree, in document order. A flat list passes through. */
+export function ruleLeaves(nodes: FilterRuleNode[]): FilterRule[] {
+  const out: FilterRule[] = [];
+  for (const node of nodes) {
+    if (isRuleGroup(node)) out.push(...ruleLeaves(node.children ?? []));
+    else out.push(node);
+  }
+  return out;
+}
+
 // ============================================================================
 // Validation Helpers
 // ============================================================================
@@ -701,22 +967,25 @@ export function getValidOperators(fieldType: FieldType): ValidOperators {
     case 'string':
       return [
         'eq', 'ne', 'contains', 'not_contains', 'startswith', 'endswith',
-        'matches', 'in', 'not_in', 'isnull', 'isnotnull'
+        'matches', 'in', 'not_in', 'exists', 'not_exists', 'isnull', 'isnotnull'
       ];
 
     case 'number':
       return [
-        'eq', 'ne', 'gt', 'lt', 'gte', 'lte',
-        'in', 'not_in', 'isnull', 'isnotnull'
+        'eq', 'ne', 'gt', 'lt', 'gte', 'lte', 'between',
+        'in', 'not_in', 'exists', 'not_exists', 'isnull', 'isnotnull'
       ];
 
     case 'boolean':
-      return ['eq', 'ne', 'is_true', 'is_false', 'isnull', 'isnotnull'];
+      return ['eq', 'ne', 'is_true', 'is_false', 'exists', 'not_exists', 'isnull', 'isnotnull'];
+
+    case 'enum':
+      return ['eq', 'ne', 'in', 'not_in', 'exists', 'not_exists'];
 
     case 'date':
       return [
-        'eq', 'ne', 'gt', 'lt', 'gte', 'lte',
-        'isnull', 'isnotnull'
+        'eq', 'ne', 'gt', 'lt', 'gte', 'lte', 'between',
+        'exists', 'not_exists', 'isnull', 'isnotnull'
       ];
 
     case 'array':
@@ -726,17 +995,17 @@ export function getValidOperators(fieldType: FieldType): ValidOperators {
       ];
 
     case 'tag':
-      return ['has_tag', 'not_has_tag'];
+      return ['has_tag', 'not_has_tag', 'exists', 'not_exists'];
 
     case 'object':
-      return ['isnull', 'isnotnull'];
+      return ['exists', 'not_exists', 'isnull', 'isnotnull'];
 
     case 'any':
     default:
       return [
-        'eq', 'ne', 'gt', 'lt', 'gte', 'lte',
+        'eq', 'ne', 'gt', 'lt', 'gte', 'lte', 'between',
         'contains', 'not_contains', 'startswith', 'endswith',
-        'in', 'not_in', 'isnull', 'isnotnull'
+        'in', 'not_in', 'exists', 'not_exists', 'isnull', 'isnotnull'
       ];
   }
 }
@@ -758,20 +1027,41 @@ export function isValidOperator(
 export function validateFilterRule(rule: FilterRule): string[] {
   const errors: string[] = [];
 
-  if (!rule.fieldPath) {
-    errors.push('fieldPath is required');
+  if (!ruleField(rule)) {
+    errors.push('field is required');
   }
 
   if (!rule.operator) {
     errors.push('operator is required');
   }
 
-  // Value required for most operators
-  const nullOps = ['isnull', 'isnotnull', 'is_true', 'is_false'];
+  // Operators that carry no value. exists/not_exists are the backend's own
+  // no-value operators (validate_value_shape → ValueShape.NONE).
+  const nullOps: Operator[] = [
+    'exists',
+    'not_exists',
+    'isnull',
+    'isnotnull',
+    'is_true',
+    'is_false',
+  ];
   if (!nullOps.includes(rule.operator) && rule.value === undefined) {
     errors.push(`value is required for operator '${rule.operator}'`);
   }
 
+  if (rule.operator === 'between') {
+    const value = rule.value;
+    if (!Array.isArray(value) || value.length !== 2) {
+      errors.push("operator 'between' requires [min, max]");
+    }
+  }
+
+  if ((rule.operator === 'in' || rule.operator === 'not_in') && rule.value !== undefined) {
+    if (!Array.isArray(rule.value) || rule.value.length === 0) {
+      errors.push(`operator '${rule.operator}' requires a non-empty array`);
+    }
+  }
+
   return errors;
 }