@ram_28/kf-ai-sdk 1.0.5 → 1.0.8

package/dist/types/common.d.ts

@@ -12,30 +12,27 @@ export type SortOption = Record<string, SortDirection>;
  */
 export type Sort = SortOption[];
 /**
- * Filter operators for individual conditions (leaf nodes)
+ * Condition operators for individual conditions (leaf nodes)
+ * Used in Condition.Operator
  */
-export type FilterOperator = "EQ" | "NE" | "GT" | "GTE" | "LT" | "LTE" | "Between" | "NotBetween" | "IN" | "NIN" | "Empty" | "NotEmpty" | "Contains" | "NotContains" | "MinLength" | "MaxLength";
+export type ConditionOperator = "EQ" | "NE" | "GT" | "GTE" | "LT" | "LTE" | "Between" | "NotBetween" | "IN" | "NIN" | "Empty" | "NotEmpty" | "Contains" | "NotContains" | "MinLength" | "MaxLength";
 /**
- * Logical operators for combining filter conditions (tree nodes)
+ * Operators for combining conditions in a group (tree nodes)
+ * Used in ConditionGroup.Operator
  */
-export type LogicalOperator = "And" | "Or" | "Not";
+export type ConditionGroupOperator = "And" | "Or" | "Not";
 /**
  * RHS value type for filter conditions
  */
 export type FilterRHSType = "Constant" | "BOField" | "AppVariable";
 /**
- * Base interface for all filter nodes
+ * Leaf condition (actual field comparison)
  */
-interface FilterNodeBase {
-    /** Operator type */
-    Operator: FilterOperator | LogicalOperator;
-}
-/**
- * Leaf filter condition (actual field comparison)
- */
-export interface FilterCondition extends FilterNodeBase {
+export interface Condition {
+    /** Optional ID for hook state management (omitted in API payload) */
+    id?: string;
     /** Condition operator */
-    Operator: FilterOperator;
+    Operator: ConditionOperator;
     /** Left-hand side field name */
     LHSField: string;
     /** Right-hand side value */
@@ -44,23 +41,36 @@ export interface FilterCondition extends FilterNodeBase {
     RHSType?: FilterRHSType;
 }
 /**
- * Logical filter node (combines multiple conditions)
+ * Group combining conditions (recursive structure)
  */
-export interface FilterLogical extends FilterNodeBase {
-    /** Logical operator */
-    Operator: LogicalOperator;
-    /** Nested conditions (can be FilterCondition or FilterLogical) */
-    Condition: Array<FilterCondition | FilterLogical>;
+export interface ConditionGroup {
+    /** Optional ID for hook state management (omitted in API payload) */
+    id?: string;
+    /** Group operator (And, Or, Not) */
+    Operator: ConditionGroupOperator;
+    /** Nested conditions (can be Condition or ConditionGroup) */
+    Condition: Array<Condition | ConditionGroup>;
 }
 /**
- * Filter structure matching API specification (root level)
- * This is a discriminated union - a filter is either a logical node or a condition
+ * Root filter type (alias for ConditionGroup)
+ */
+export type Filter = ConditionGroup;
+/**
+ * @deprecated Use `Condition` instead
+ */
+export type FilterCondition = Condition;
+/**
+ * @deprecated Use `ConditionGroup` instead
+ */
+export type FilterLogical = ConditionGroup;
+/**
+ * @deprecated Use `ConditionGroupOperator` instead
  */
-export type Filter = FilterLogical;
+export type FilterOperator = ConditionGroupOperator;
 /**
- * Convenience type for any filter node (leaf or logical)
+ * @deprecated Use `Condition | ConditionGroup` instead
  */
-export type FilterNode = FilterCondition | FilterLogical;
+export type FilterNode = Condition | ConditionGroup;
 /**
  * DateTime encoding format used by the API
  */
@@ -234,5 +244,4 @@ export interface FetchFieldResponse {
     /** Array of field options */
     Data: FetchFieldOption[];
 }
-export {};
 //# sourceMappingURL=common.d.ts.map

package/dist/types/common.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../sdk/types/common.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../sdk/types/common.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,MAAM,CAAC;AAE3C;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAEvD;;GAEG;AACH,MAAM,MAAM,IAAI,GAAG,UAAU,EAAE,CAAC;AAEhC;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GACzB,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,GACzC,SAAS,GAAG,YAAY,GAAG,IAAI,GAAG,KAAK,GACvC,OAAO,GAAG,UAAU,GAAG,UAAU,GAAG,aAAa,GACjD,WAAW,GAAG,WAAW,CAAC;AAE9B;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,CAAC;AAE1D;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,SAAS,GAAG,aAAa,CAAC;AAEnE;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,qEAAqE;IACrE,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,yBAAyB;IACzB,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,gCAAgC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,4BAA4B;IAC5B,QAAQ,EAAE,GAAG,CAAC;IACd,4DAA4D;IAC5D,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,qEAAqE;IACrE,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,oCAAoC;IACpC,QAAQ,EAAE,sBAAsB,CAAC;IACjC,6DAA6D;IAC7D,SAAS,EAAE,KAAK,CAAC,SAAS,GAAG,cAAc,CAAC,CAAC;CAC9C;AAED;;GAEG;AACH,MAAM,MAAM,MAAM,GAAG,cAAc,CAAC;AAMpC;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,SAAS,CAAC;AAExC;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,cAAc,CAAC;AAE3C;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,sBAAsB,CAAC;AAEpD;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,cAAc,CAAC;AAEpD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,sCAAsC;IACtC,IAAI,EAAE,CAAC,EAAE,CAAC;CACX;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,sBAAsB;IACtB,IAAI,EAAE,CAAC,CAAC;CACT;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,uCAAuC;IACvC,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,qCAAqC;IACrC,MAAM,EAAE,SAAS,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAEjB,sBAAsB;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,yBAAyB;IACzB,IAAI,CAAC,EAAE,IAAI,CAAC;IAEZ,2CAA2C;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,8BAA8B;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,uBAAuB;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAMD;;GAEG;AACH,MAAM,MAAM,UAAU,GAClB,KAAK,GACL,KAAK,GACL,OAAO,GACP,KAAK,GACL,KAAK,GACL,eAAe,GACf,YAAY,GACZ,eAAe,GACf,QAAQ,GACR,gBAAgB,CAAC;AAErB;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,IAAI,EAAE,UAAU,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,mCAAmC;IACnC,IAAI,EAAE,QAAQ,CAAC;IACf,yBAAyB;IACzB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,yBAAyB;IACzB,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,+BAA+B;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;CAC7B;AAMD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,uBAAuB;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,wCAAwC;IACxC,QAAQ,CAAC,EAAE,eAAe,EAAE,GAAG,IAAI,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,kBAAkB;IAClB,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,qBAAqB;IACrB,YAAY,EAAE,eAAe,EAAE,CAAC;IAChC,iCAAiC;IACjC,KAAK,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,EAAE,EAAE,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,kCAAkC;IAClC,IAAI,EAAE,OAAO,CAAC;IACd,2BAA2B;IAC3B,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,8BAA8B;IAC9B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,yBAAyB;IACzB,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,+BAA+B;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,8CAA8C;IAC9C,IAAI,EAAE,iBAAiB,CAAC;CACzB;AAMD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,4BAA4B;IAC5B,CAAC,SAAS,EAAE,MAAM,GAAG,GAAG,CAAC;CAC1B;AAMD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;CAC7B;AAMD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,6BAA6B;IAC7B,IAAI,EAAE,gBAAgB,EAAE,CAAC;CAC1B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ram_28/kf-ai-sdk",
-  "version": "1.0.5",
+  "version": "1.0.8",
   "description": "Type-safe, AI-driven SDK for building modern web applications with role-based access control",
   "author": "Ramprasad",
   "license": "MIT",

package/sdk/api/index.ts

@@ -26,12 +26,16 @@ export type {
   SortDirection,
   SortOption,
   Sort,
-  // Filter types
+  // Filter types (new names)
+  Condition,
+  ConditionGroup,
+  ConditionGroupOperator,
   Filter,
+  FilterRHSType,
+  ConditionOperator,
+  // Filter types (legacy - deprecated)
   FilterCondition,
   FilterOperator,
-  FilterRHSType,
-  LogicalOperator,
   FilterLogical,
   FilterNode,
   // List types

package/sdk/components/hooks/useFilter/index.ts

@@ -1,37 +1,25 @@
 // Main hook export
-export { useFilter } from './useFilter';
+export { useFilter } from "./useFilter";
 
-// Type exports
+// Type exports (new names)
 export type {
-  FilterConditionWithId,
-  TypedFilterConditionInput,
-  FilterState,
-  FieldDefinition,
-  ValidationResult,
-  ValidationError,
+  Condition,
+  ConditionGroup,
+  ConditionGroupOperator,
+  Filter,
+  FilterRHSType,
   UseFilterOptions,
-  UseFilterReturn
-} from './types';
+  UseFilterReturn,
+  // Legacy type exports
+  FilterCondition,
+  FilterOperator,
+} from "./types";
 
-// Validation utilities
+// Type guard exports
 export {
-  validateNumberValue,
-  validateDateValue,
-  validateCurrencyValue,
-  validateStringValue,
-  validateBooleanValue,
-  validateSelectValue,
-  getDefaultFieldDefinition,
-  createFieldDefinitionsFromSample
-} from './validation.utils';
-
-// Payload building utilities
-export {
-  buildFilterPayload,
-  buildFilterPayloadFromState,
-  validateFilterPayload,
-  cloneFilterPayload,
-  mergeFilterPayloads,
-  filterPayloadToString,
-  areFilterPayloadsEqual
-} from './payloadBuilder.utils';
+  isCondition,
+  isConditionGroup,
+  // Legacy type guard exports
+  isFilterCondition,
+  isFilterLogical,
+} from "./types";

package/sdk/components/hooks/useFilter/types.ts

@@ -1,158 +1,177 @@
-import type { Filter, FilterOperator, FilterRHSType, LogicalOperator } from "../../../types/common";
+import type {
+  Condition,
+  ConditionGroup,
+  ConditionGroupOperator,
+  Filter,
+  FilterRHSType,
+  // Legacy types for backwards compatibility
+  FilterCondition,
+  FilterOperator,
+} from "../../../types/common";
+
+// Re-export from common types for convenience
+export type {
+  Condition,
+  ConditionGroup,
+  ConditionGroupOperator,
+  Filter,
+  FilterRHSType,
+  // Legacy re-exports
+  FilterCondition,
+  FilterOperator,
+};
 
 // ============================================================
-// TYPE DEFINITIONS
+// TYPE GUARDS
 // ============================================================
 
 /**
- * Internal filter condition with ID for management
- * Supports both simple conditions and nested logical groups
+ * Type guard to check if an item is a ConditionGroup (has nested Condition array)
  */
-export interface FilterConditionWithId {
-  /** Unique identifier for internal management */
-  id: string;
-  /** Filter operator (can be condition or logical operator) */
-  operator: FilterOperator | LogicalOperator;
-  /** Left-hand side field name (required for condition operators) */
-  lhsField?: string;
-  /** Right-hand side value (required for condition operators) */
-  rhsValue?: any;
-  /** Right-hand side type (defaults to Constant) */
-  rhsType?: FilterRHSType;
-  /** Nested conditions (for logical operators: And, Or, Not) */
-  children?: FilterConditionWithId[];
-  /** Validation state */
-  isValid: boolean;
-  /** Specific validation errors */
-  validationErrors?: string[];
-}
+export const isConditionGroup = (
+  item: Condition | ConditionGroup
+): item is ConditionGroup => {
+  return "Condition" in item;
+};
 
 /**
- * Type-safe filter condition input (for addCondition)
- * Constrains lhsField to keys of T for compile-time type checking
+ * Type guard to check if an item is a leaf Condition (has LHSField)
  */
-export interface TypedFilterConditionInput<T> {
-  /** Filter operator (can be condition or logical operator) */
-  operator: FilterOperator | LogicalOperator;
-  /** Left-hand side field name - constrained to keyof T */
-  lhsField?: keyof T & string;
-  /** Right-hand side value */
-  rhsValue?: T[keyof T] | T[keyof T][] | any;
-  /** Right-hand side type (defaults to Constant) */
-  rhsType?: FilterRHSType;
-  /** Nested conditions (for logical operators: And, Or, Not) */
-  children?: TypedFilterConditionInput<T>[];
-}
+export const isCondition = (
+  item: Condition | ConditionGroup
+): item is Condition => {
+  return "LHSField" in item;
+};
 
-export interface FilterState {
-  /** Logical operator for combining conditions */
-  logicalOperator: LogicalOperator;
-  /** Array of filter conditions with IDs */
-  conditions: FilterConditionWithId[];
-}
+// ============================================================
+// LEGACY TYPE GUARDS (for backwards compatibility)
+// ============================================================
 
-export interface FieldDefinition {
-  /** Field data type */
-  type: 'string' | 'number' | 'date' | 'boolean' | 'currency' | 'select';
-  /** Operators allowed for this field type */
-  allowedOperators: FilterOperator[];
-  /** Custom value validation function */
-  validateValue?: (value: any, operator: FilterOperator) => ValidationResult;
-  /** Value transformation function */
-  transformValue?: (value: any) => any;
-  /** Options for select fields */
-  selectOptions?: Array<{ label: string; value: any }>;
-}
+/**
+ * @deprecated Use `isConditionGroup` instead
+ */
+export const isFilterLogical = isConditionGroup;
 
-export interface ValidationResult {
-  /** Whether the validation passed */
-  isValid: boolean;
-  /** Array of error messages */
-  errors: string[];
-}
+/**
+ * @deprecated Use `isCondition` instead
+ */
+export const isFilterCondition = isCondition;
 
-export interface ValidationError {
-  /** ID of the condition with errors */
-  conditionId: string;
-  /** Field name */
-  field: string;
-  /** Error message */
-  message: string;
-}
+// ============================================================
+// HOOK-SPECIFIC TYPE DEFINITIONS
+// ============================================================
 
-export interface UseFilterOptions<T = any> {
+/**
+ * Hook options (minimal configuration)
+ */
+export interface UseFilterOptions {
   /** Initial filter conditions */
-  initialConditions?: FilterConditionWithId[];
-  /** Initial logical operator */
-  initialLogicalOperator?: LogicalOperator;
-  /** Field definitions for validation */
-  fieldDefinitions?: Record<keyof T, FieldDefinition>;
-  /** Whether to validate conditions on change */
-  validateOnChange?: boolean;
-  /** Callback when condition is added */
-  onConditionAdd?: (condition: FilterConditionWithId) => void;
-  /** Callback when condition is updated */
-  onConditionUpdate?: (condition: FilterConditionWithId) => void;
-  /** Callback when condition is removed */
-  onConditionRemove?: (conditionId: string) => void;
-  /** Callback when validation errors occur */
-  onValidationError?: (errors: ValidationError[]) => void;
+  initialConditions?: Array<Condition | ConditionGroup>;
+  /** Initial operator for combining conditions (defaults to "And") */
+  initialOperator?: ConditionGroupOperator;
 }
 
-export interface UseFilterReturn<T = any> {
-  // Current state
-  /** Array of current filter conditions */
-  conditions: FilterConditionWithId[];
-  /** Current logical operator */
-  logicalOperator: LogicalOperator;
-  /** SDK-formatted filter payload for API calls */
-  filterPayload: Filter | undefined;
-  /** Overall validation state */
-  isValid: boolean;
-  /** Array of validation errors */
-  validationErrors: ValidationError[];
-
-  // Condition management
-  /** Add a new filter condition (type-safe: lhsField constrained to keyof T) */
-  addCondition: (condition: TypedFilterConditionInput<T>) => string;
-  /** Update an existing condition */
-  updateCondition: (id: string, updates: Partial<TypedFilterConditionInput<T>>) => boolean;
-  /** Remove a condition by ID */
-  removeCondition: (id: string) => boolean;
-  /** Clear all conditions */
-  clearConditions: () => void;
-  /** Get a specific condition by ID */
-  getCondition: (id: string) => FilterConditionWithId | undefined;
-
-  // Logical operator management
-  /** Set the root logical operator */
-  setLogicalOperator: (operator: LogicalOperator) => void;
-
-  // Bulk operations
-  /** Replace all conditions */
-  setConditions: (conditions: FilterConditionWithId[]) => void;
-  /** Replace a specific condition */
-  replaceCondition: (id: string, newCondition: TypedFilterConditionInput<T>) => boolean;
-
-  // Validation
-  /** Validate a single condition */
-  validateCondition: (condition: Partial<FilterConditionWithId>) => ValidationResult;
-  /** Validate all current conditions */
-  validateAllConditions: () => ValidationResult;
-
-  // State management
-  /** Export current filter state */
-  exportState: () => FilterState;
-  /** Import a filter state */
-  importState: (state: FilterState) => void;
-  /** Reset to initial state */
-  resetToInitial: () => void;
-
-  // Utilities
-  /** Get total number of conditions */
-  getConditionCount: () => number;
+/**
+ * Hook return interface with nested filter support
+ */
+export interface UseFilterReturn {
+  // ============================================================
+  // STATE (read-only)
+  // ============================================================
+
+  /** Current operator for combining root-level conditions ("And" | "Or" | "Not") */
+  operator: ConditionGroupOperator;
+
+  /** Current filter items (with id populated) */
+  items: Array<Condition | ConditionGroup>;
+
+  /** Ready-to-use API payload (id stripped, undefined if no conditions) */
+  payload: Filter | undefined;
+
   /** Whether any conditions exist */
   hasConditions: boolean;
-  /** Whether more conditions can be added */
-  canAddCondition: boolean;
+
+  // ============================================================
+  // ADD OPERATIONS (return id of created item)
+  // ============================================================
+
+  /**
+   * Add a leaf condition at root level
+   * @returns The id of the created condition
+   */
+  add: (condition: Omit<Condition, "id">) => string;
+
+  /**
+   * Add a condition group at root level
+   * @returns The id of the created group
+   */
+  addGroup: (operator: ConditionGroupOperator) => string;
+
+  /**
+   * Add a leaf condition to a specific parent group
+   * @param parentId - The id of the parent ConditionGroup
+   * @returns The id of the created condition
+   */
+  addTo: (parentId: string, condition: Omit<Condition, "id">) => string;
+
+  /**
+   * Add a condition group to a specific parent group
+   * @param parentId - The id of the parent ConditionGroup
+   * @returns The id of the created group
+   */
+  addGroupTo: (parentId: string, operator: ConditionGroupOperator) => string;
+
+  // ============================================================
+  // UPDATE OPERATIONS
+  // ============================================================
+
+  /**
+   * Update a leaf condition by id
+   * @param id - The id of the condition to update
+   * @param updates - Partial updates to apply
+   */
+  update: (id: string, updates: Partial<Omit<Condition, "id">>) => void;
+
+  /**
+   * Update a condition group's operator by id
+   * @param id - The id of the group to update
+   * @param operator - The new operator
+   */
+  updateOperator: (id: string, operator: ConditionGroupOperator) => void;
+
+  // ============================================================
+  // REMOVE & ACCESS
+  // ============================================================
+
+  /**
+   * Remove a condition or group by id
+   * @param id - The id of the item to remove
+   */
+  remove: (id: string) => void;
+
+  /**
+   * Get a condition or group by id
+   * @param id - The id to look up
+   * @returns The item or undefined if not found
+   */
+  get: (id: string) => Condition | ConditionGroup | undefined;
+
+  // ============================================================
+  // UTILITY
+  // ============================================================
+
+  /** Clear all conditions */
+  clear: () => void;
+
+  /** Set the root operator for combining conditions */
+  setOperator: (op: ConditionGroupOperator) => void;
+
+  // ============================================================
+  // LEGACY API (for backwards compatibility)
+  // ============================================================
+
+  /**
+   * @deprecated Use `items` instead
+   */
+  conditions: Array<Condition | ConditionGroup>;
 }