api-chain-runner 2.5.3__tar.gz → 2.5.5__tar.gz

{api_chain_runner-2.5.3 → api_chain_runner-2.5.5}/.gitignore

@@ -18,6 +18,7 @@ env/
 .kiro/
 *.swp
 *.swo
+.hypothesis
 
 # OS
 .DS_Store

{api_chain_runner-2.5.3/api_chain_runner.egg-info → api_chain_runner-2.5.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: api-chain-runner
-Version: 2.5.3
+Version: 2.5.5
 Summary: Execute chained API calls defined in YAML configuration files
 Author-email: Sambit Saha <creativesambit@gmail.com>
 License: MIT
@@ -330,10 +330,10 @@ files:
 
 ### Conditional Steps
 
-Skip steps based on previous responses:
+Condition operators include `equals` (the default), `not_equals`, `contains`, `not_contains`, `greater_than`, `greater_than_or_equal`, `less_than`, `less_than_or_equal`, `starts_with`, `ends_with`, `is_null`, and `is_not_null`. Multiple conditions are ANDed. Use `contains` for list membership; unlike `eval_condition`, a `condition` controls whether the dependent step runs.
 
 ```yaml
-# Single condition
+# Single condition (operator defaults to `equals`)
 - name: generate-link
   url: "https://api.example.com/link"
   method: POST
@@ -342,6 +342,16 @@ Skip steps based on previous responses:
     key_path: "status"
     expected_value: "PENDING"
 
+# List membership
+- name: next-step
+  url: "https://api.example.com/next"
+  method: POST
+  condition:
+    step: get-lead-status
+    key_path: "lead_status"
+    operator: contains
+    expected_value: "okyc"
+
 # Multiple conditions (ALL must pass)
 - name: ready-to-sanction
   url: "https://api.example.com/sanction"

{api_chain_runner-2.5.3 → api_chain_runner-2.5.5}/PYPI_README.md

@@ -302,10 +302,10 @@ files:
 
 ### Conditional Steps
 
-Skip steps based on previous responses:
+Condition operators include `equals` (the default), `not_equals`, `contains`, `not_contains`, `greater_than`, `greater_than_or_equal`, `less_than`, `less_than_or_equal`, `starts_with`, `ends_with`, `is_null`, and `is_not_null`. Multiple conditions are ANDed. Use `contains` for list membership; unlike `eval_condition`, a `condition` controls whether the dependent step runs.
 
 ```yaml
-# Single condition
+# Single condition (operator defaults to `equals`)
 - name: generate-link
   url: "https://api.example.com/link"
   method: POST
@@ -314,6 +314,16 @@ Skip steps based on previous responses:
     key_path: "status"
     expected_value: "PENDING"
 
+# List membership
+- name: next-step
+  url: "https://api.example.com/next"
+  method: POST
+  condition:
+    step: get-lead-status
+    key_path: "lead_status"
+    operator: contains
+    expected_value: "okyc"
+
 # Multiple conditions (ALL must pass)
 - name: ready-to-sanction
   url: "https://api.example.com/sanction"

{api_chain_runner-2.5.3 → api_chain_runner-2.5.5}/README.md

@@ -467,7 +467,7 @@ Manual steps are logged to CSV as `MANUAL — completed by user`.
 Only execute a step if a previous step's response matches a specific value. You can use a single condition or multiple conditions (all must pass):
 
 ```yaml
-# Single condition
+# Single condition (operator defaults to equals for backward compatibility)
 - name: generate-registration-link
   url: "https://api.example.com/registration-link"
   method: POST
@@ -475,6 +475,16 @@ Only execute a step if a previous step's response matches a specific value. You
     step: check-status
     key_path: "businessProofVerification"
     expected_value: "PENDING"
+
+# List membership — runs only when the value is present in the list
+- name: next-step
+  url: "https://api.example.com/next"
+  method: POST
+  condition:
+    step: get-lead-status
+    key_path: "lead_status"
+    operator: contains
+    expected_value: "okyc"
   headers:
     Authorization: "Bearer ${auth.token}"
   payload:
@@ -497,7 +507,17 @@ Only execute a step if a previous step's response matches a specific value. You
     leadId: "${lead.id}"
 ```
 
-If any condition is not met, the step is skipped with a message:
+Conditions support these operators:
+
+- `equals` (default) — exact value match; omitting `operator` preserves existing behavior
+- `not_equals` — value does not equal the expected value
+- `contains` / `not_contains` — expected value is (or is not) in a list, string, or mapping
+- `greater_than`, `greater_than_or_equal`, `less_than`, `less_than_or_equal` — numeric or string comparisons
+- `starts_with` / `ends_with` — string prefix/suffix checks
+- `is_null` / `is_not_null` — check whether the response value is null; expected value may be blank
+
+Multiple conditions are ANDed together. If you need to check whether `okyc` appears anywhere in `lead_status`, use `operator: contains` rather than `eval_condition`; `eval_condition` reports a result but does not control later-step execution.
+
 
 ```
 [9/12] ⏭ generate-registration-link — skipped (condition not met: businessProofVerification='COMPLETED', expected 'PENDING')

{api_chain_runner-2.5.3 → api_chain_runner-2.5.5}/api_chain_runner/__init__.py

@@ -1,6 +1,6 @@
 """API Chain Runner — execute chained API calls with dynamic reference resolution."""
 
-__version__ = "2.5.3"
+__version__ = "2.5.5"
 
 from api_chain_runner.runner import ChainRunner
 from api_chain_runner.generator import UniqueDataGenerator

{api_chain_runner-2.5.3 → api_chain_runner-2.5.5}/api_chain_runner/models.py

@@ -30,13 +30,34 @@ class PollingConfig:
     expected_values: list[str] | None = None  # list of acceptable values (e.g. ["APPROVED", "COMPLETED"])
 
 
+VALID_CONDITION_OPERATORS = frozenset({
+    "equals",
+    "not_equals",
+    "contains",
+    "not_contains",
+    "greater_than",
+    "greater_than_or_equal",
+    "less_than",
+    "less_than_or_equal",
+    "starts_with",
+    "ends_with",
+    "is_null",
+    "is_not_null",
+})
+
+
 @dataclass
 class ConditionConfig:
-    """Condition to check before executing a step."""
+    """Condition to check before executing a step.
+
+    ``operator`` defaults to ``equals`` so existing condition configurations
+    retain their original exact-string comparison behavior.
+    """
 
     step: str  # name of the previous step whose response to check
     key_path: str  # dot-notation path in that step's response
-    expected_value: str  # value that must match for this step to run
+    expected_value: str  # value used by the operator
+    operator: str = "equals"
 
 
 # Default retry: 3 attempts on timeout/connection/5xx errors

{api_chain_runner-2.5.3 → api_chain_runner-2.5.5}/api_chain_runner/runner.py

@@ -18,6 +18,7 @@ from api_chain_runner.models import (
     PollingConfig,
     StepDefinition,
     StepResult,
+    VALID_CONDITION_OPERATORS,
     validate_steps,
 )
 from api_chain_runner.pause import PauseController
@@ -189,10 +190,17 @@ class ChainRunner:
                             raise ConfigurationError(
                                 f"Step '{entry['name']}': condition missing required field '{req_field}'."
                             )
+                    operator = str(ci.get("operator", "equals")).strip().lower()
+                    if operator not in VALID_CONDITION_OPERATORS:
+                        raise ConfigurationError(
+                            f"Step '{entry['name']}': invalid condition operator '{operator}'. "
+                            f"Must be one of {sorted(VALID_CONDITION_OPERATORS)}."
+                        )
                     conditions.append(ConditionConfig(
                         step=ci["step"],
                         key_path=ci["key_path"],
                         expected_value=str(ci["expected_value"]),
+                        operator=operator,
                     ))
                 condition = conditions
 
@@ -314,6 +322,55 @@ class ChainRunner:
         if variables and isinstance(variables, dict):
             self.store.save("vars", variables)
 
+    @staticmethod
+    def condition_matches(actual, condition: ConditionConfig) -> bool:
+        """Return whether an extracted value satisfies a configured condition."""
+        operator = condition.operator or "equals"
+        expected = condition.expected_value
+
+        if operator == "equals":
+            return str(actual) == str(expected)
+        if operator == "not_equals":
+            return str(actual) != str(expected)
+        if operator == "contains":
+            try:
+                return expected in actual
+            except TypeError:
+                return False
+        if operator == "not_contains":
+            try:
+                return expected not in actual
+            except TypeError:
+                return True
+        if operator == "is_null":
+            return actual is None
+        if operator == "is_not_null":
+            return actual is not None
+        if operator in {"starts_with", "ends_with"}:
+            if not isinstance(actual, str):
+                return False
+            return (actual.startswith if operator == "starts_with" else actual.endswith)(str(expected))
+
+        try:
+            if isinstance(actual, bool):
+                comparable_expected = str(expected).lower() == "true"
+            elif isinstance(actual, (int, float)):
+                comparable_expected = float(expected)
+            else:
+                comparable_expected = str(expected)
+            if operator == "greater_than":
+                return actual > comparable_expected
+            if operator == "greater_than_or_equal":
+                return actual >= comparable_expected
+            if operator == "less_than":
+                return actual < comparable_expected
+            if operator == "less_than_or_equal":
+                return actual <= comparable_expected
+        except (TypeError, ValueError):
+            return False
+
+        return False
+
     def run(self) -> ChainResult:
         """Execute all steps in the chain sequentially.
 
@@ -350,9 +407,9 @@ class ChainRunner:
                         if self.store.has(cond.step):
                             stored = self.store.get_raw(cond.step)
                             actual = StepExecutor._get_nested(stored, cond.key_path)
-                            if str(actual) != cond.expected_value:
+                            if not self.condition_matches(actual, cond):
                                 print(f"[{idx}/{total}] ⏭ {step.name} — skipped (condition not met: "
-                                      f"{cond.key_path}='{actual}', expected '{cond.expected_value}')")
+                                      f"{cond.key_path}='{actual}', {cond.operator} '{cond.expected_value}')")
                                 skip = True
                                 break
                         else:

{api_chain_runner-2.5.3 → api_chain_runner-2.5.5}/api_chain_runner/ui/server.py

@@ -7,12 +7,14 @@ import json
 import os
 import threading
 import webbrowser
+from datetime import datetime
 from pathlib import Path
 
 import yaml
 from flask import Flask, jsonify, render_template, request
 
 from api_chain_runner.runner import ChainRunner
+from api_chain_runner.models import VALID_CONDITION_OPERATORS
 
 app = Flask(
     __name__,
@@ -24,6 +26,11 @@ app = Flask(
 _flow_dir: str = "."
 
 
+def _local_timestamp() -> str:
+    """Return the local timezone timestamp used by the UI response timeline."""
+    return datetime.now().astimezone().isoformat(timespec="seconds")
+
+
 def _discover_flows(base_dir: str) -> list[dict]:
     """Recursively find all .yaml/.yml files and extract chain metadata."""
     flows = []
@@ -55,6 +62,51 @@ def _discover_flows(base_dir: str) -> list[dict]:
     return flows
 
 
+def _normalize_conditions(value, *, field_name="condition") -> list[dict[str, str]]:
+    """Return condition data in the UI's ordered-list representation.
+
+    ChainRunner accepts both the legacy single mapping form and the current
+    list form.  The UI always receives and persists a list, with values
+    normalized to strings so the result can be loaded by ChainRunner without
+    changing condition comparison semantics.
+    """
+    if value is None:
+        return []
+    entries = [value] if isinstance(value, dict) else value
+    if not isinstance(entries, list):
+        raise ValueError(f"'{field_name}' must be a mapping or list of mappings")
+
+    normalized = []
+    required = ("step", "key_path", "expected_value")
+    for index, entry in enumerate(entries):
+        if not isinstance(entry, dict):
+            raise ValueError(f"condition at index {index} must be a mapping")
+        missing = [name for name in required if name not in entry]
+        if missing:
+            raise ValueError(
+                f"condition at index {index} missing required field(s): {', '.join(missing)}"
+            )
+        if not isinstance(entry["step"], str) or not entry["step"].strip():
+            raise ValueError(f"condition at index {index} 'step' must be a non-empty string")
+        if not isinstance(entry["key_path"], str) or not entry["key_path"].strip():
+            raise ValueError(f"condition at index {index} 'key_path' must be a non-empty string")
+        operator = str(entry.get("operator", "equals")).strip().lower()
+        if operator not in VALID_CONDITION_OPERATORS:
+            raise ValueError(
+                f"condition at index {index} has invalid operator '{operator}'"
+            )
+        normalized_entry = {
+            "step": entry["step"],
+            "key_path": entry["key_path"],
+            "expected_value": str(entry["expected_value"]),
+        }
+        # Keep legacy YAML/UI output unchanged when operator was omitted.
+        if "operator" in entry:
+            normalized_entry["operator"] = operator
+        normalized.append(normalized_entry)
+    return normalized
+
+
 def _parse_chain(filepath: str) -> dict:
     """Parse a YAML chain file and return structured data for visualization."""
     with open(filepath, "r", encoding="utf-8") as f:
@@ -65,6 +117,7 @@ def _parse_chain(filepath: str) -> dict:
     for step in chain:
         if not isinstance(step, dict):
             continue
+        condition = _normalize_conditions(step.get("condition"))
         step_info = {
             "name": step.get("name", "unnamed"),
             "method": step.get("method", "MANUAL") if not step.get("manual") else "MANUAL",
@@ -75,7 +128,8 @@ def _parse_chain(filepath: str) -> dict:
             "has_payload": "payload" in step,
             "has_files": "files" in step,
             "has_unique_fields": "unique_fields" in step,
-            "has_condition": "condition" in step,
+            "has_condition": bool(condition),
+            "condition": condition,
             "manual": step.get("manual", False),
             "instruction": step.get("instruction", ""),
             "print_ref": step.get("print_ref", []),
@@ -164,7 +218,37 @@ def _run_chain_thread(run_id: str, filepath: str):
             runner.pause_controller.wait_if_paused()
 
             try:
+                execution_time = None
+                if step.condition:
+                    execution_time = _local_timestamp()
+                    skip = False
+                    for cond in step.condition:
+                        if runner.store.has(cond.step):
+                            from api_chain_runner.executor import StepExecutor
+                            stored = runner.store.get_raw(cond.step)
+                            actual = StepExecutor._get_nested(stored, cond.key_path)
+                            if not runner.condition_matches(actual, cond):
+                                skip = True
+                                break
+                        else:
+                            skip = True
+                            break
+                    if skip:
+                        step_result = {
+                            "step_name": step.name,
+                            "status_code": 0,
+                            "success": True,
+                            "duration_ms": 0,
+                            "executed_at": execution_time or _local_timestamp(),
+                            "error": None,
+                            "skipped": True,
+                        }
+                        with _run_lock:
+                            _active_runs[run_id]["results"].append(step_result)
+                        continue
+
                 if step.manual:
+                    execution_time = _local_timestamp()
                     # Resolve print_ref values from previous steps
                     resolved_refs = {}
                     if step.print_ref:
@@ -207,42 +291,16 @@ def _run_chain_thread(run_id: str, filepath: str):
                         "status_code": 0,
                         "success": True,
                         "duration_ms": 0,
+                        "executed_at": execution_time,
                         "error": None,
                         "manual": True,
                     }
-                    if resolved_refs:
-                        step_result["printed_keys"] = resolved_refs
                 else:
-                    if step.condition:
-                        skip = False
-                        for cond in step.condition:
-                            if runner.store.has(cond.step):
-                                from api_chain_runner.executor import StepExecutor
-                                stored = runner.store.get_raw(cond.step)
-                                actual = StepExecutor._get_nested(stored, cond.key_path)
-                                if str(actual) != cond.expected_value:
-                                    skip = True
-                                    break
-                            else:
-                                skip = True
-                                break
-                        if skip:
-                            step_result = {
-                                "step_name": step.name,
-                                "status_code": 0,
-                                "success": True,
-                                "duration_ms": 0,
-                                "error": None,
-                                "skipped": True,
-                            }
-                            with _run_lock:
-                                _active_runs[run_id]["results"].append(step_result)
-                            continue
-
                     if step.delay > 0:
                         import time
                         time.sleep(step.delay)
 
+                    execution_time = _local_timestamp()
                     result = runner.executor.execute(step)
                     resp_preview = json.dumps(result.response_body, indent=2, default=str) if isinstance(result.response_body, (dict, list)) else str(result.response_body)
 
@@ -251,6 +309,7 @@ def _run_chain_thread(run_id: str, filepath: str):
                         "status_code": result.status_code,
                         "success": result.success,
                         "duration_ms": round(result.duration_ms, 1),
+                        "executed_at": execution_time,
                         "error": result.error,
                         "response_body": resp_preview,
                     }
@@ -298,6 +357,7 @@ def _run_chain_thread(run_id: str, filepath: str):
                                     "status_code": 0,
                                     "success": False,
                                     "duration_ms": 0,
+                                    "executed_at": "",
                                     "error": "Not executed (chain aborted)",
                                     "skipped": True,
                                 }
@@ -314,6 +374,7 @@ def _run_chain_thread(run_id: str, filepath: str):
                     "status_code": -1,
                     "success": False,
                     "duration_ms": 0,
+                    "executed_at": execution_time or "",
                     "error": str(exc),
                     "response_body": "",
                 }
@@ -430,17 +491,42 @@ def api_step_update(flow_path, step_index):
             return jsonify({"error": "step index out of range"}), 400
 
         step = chain[step_index]
+        # Validate conditions before mutating any other field so malformed
+        # editor submissions cannot partially save a step.
+        normalized_condition = None
+        if "condition" in updates:
+            submitted_condition = updates["condition"]
+            if not isinstance(submitted_condition, list):
+                return jsonify({"error": "'condition' must be a list of mappings"}), 400
+            try:
+                normalized_condition = _normalize_conditions(submitted_condition)
+            except ValueError as exc:
+                return jsonify({"error": str(exc)}), 400
+
         # Apply updates to allowed fields
-        allowed = {"payload", "headers", "url", "unique_fields", "delay", "continue_on_error", "method", "files", "print_keys", "polling", "eval_keys", "eval_condition", "success_message", "failure_message", "manual", "instruction", "print_ref", "retry"}
+        allowed = {"payload", "headers", "url", "unique_fields", "delay", "continue_on_error", "method", "files", "print_keys", "polling", "eval_keys", "eval_condition", "success_message", "failure_message", "manual", "instruction", "print_ref", "retry", "condition"}
         for key, value in updates.items():
-            if key in allowed:
-                if value is None or value == "":
-                    step.pop(key, None)
+            if key not in allowed:
+                continue
+            if key == "condition":
+                if normalized_condition:
+                    step[key] = normalized_condition
                 else:
-                    step[key] = value
+                    # An explicit empty list is the clearing contract.
+                    step.pop(key, None)
+            elif value is None or value == "":
+                step.pop(key, None)
+            else:
+                step[key] = value
 
         # Write back preserving original formatting as much as possible
-        dumped = yaml.dump(raw, default_flow_style=False, allow_unicode=True, sort_keys=False)
+        dumped = yaml.dump(
+            raw,
+            default_flow_style=False,
+            allow_unicode=True,
+            sort_keys=False,
+            default_style='"',
+        )
         formatted = _format_yaml_for_readability(dumped)
         with open(abs_path, "w", encoding="utf-8") as f:
             f.write(formatted)