/**
 * Workflow context types for variable picker and data flow
 *
 * These types support the namespaced data flow between workflow nodes,
 * enabling the variable picker UI to show available data from preceding nodes.
 */

/**
 * Supported data types for context variables
 */
export type ContextVariableType = 'string' | 'integer' | 'boolean' | 'datetime' | 'array';

/**
 * Valid context variable types for runtime validation
 */
const VALID_CONTEXT_TYPES: readonly ContextVariableType[] = [
  'string',
  'integer',
  'boolean',
  'datetime',
  'array',
] as const;

/**
 * Validates and normalizes a field type from the API.
 * Returns 'string' as default for unknown types.
 *
 * @param type - The type string from the API
 * @returns A valid ContextVariableType
 */
export function validateContextType(type: string): ContextVariableType {
  return VALID_CONTEXT_TYPES.includes(type as ContextVariableType)
    ? (type as ContextVariableType)
    : 'string';
}

/**
 * Represents a single variable available in workflow context
 */
export interface ContextVariable {
  /** Full variable path for template syntax (e.g., "Trigger.user_email", "CreatePost.post_id") */
  path: string;
  /** Human-readable display label (e.g., "User Email", "Post ID") */
  label: string;
  /** Source node display name (e.g., "User Registration", "Create/Update Post") */
  source: string;
  /** Source namespace key (e.g., "Trigger", "create_post") */
  namespace: string;
  /** Data type for validation and display */
  type: ContextVariableType;
  /** Description of what this variable contains */
  description: string;
  /** Example value for preview */
  example: string;
}

/**
 * Grouped context variables by source node
 */
export interface ContextVariableGroup {
  /** Source namespace key (e.g., "Trigger", "create_post") */
  namespace: string;
  /** Display name for the source node (e.g., "User Registration", "Create Post") */
  sourceName: string;
  /** Node type for styling purposes */
  sourceType: 'trigger' | 'action';
  /** Variables from this source */
  variables: ContextVariable[];
}

/**
 * Complete available context for a specific node position
 */
export interface AvailableContext {
  /** Variables grouped by source node */
  groups: ContextVariableGroup[];
}
