@cyvest/cyvest-js 2.0.1 → 3.0.1

package/dist/index.mjs

@@ -4,286 +4,55 @@ import addFormats from "ajv-formats";
 
 // ../../../schema/cyvest.schema.json
 var cyvest_schema_default = {
-  $schema: "https://json-schema.org/draft/2020-12/schema",
-  $id: "https://cyvest.io/schema/investigation.json",
-  title: "Cyvest Investigation",
-  type: "object",
-  additionalProperties: false,
-  required: [
-    "score",
-    "level",
-    "whitelisted",
-    "whitelists",
-    "observables",
-    "checks",
-    "checks_by_level",
-    "threat_intels",
-    "enrichments",
-    "containers",
-    "stats",
-    "stats_checks",
-    "data_extraction"
-  ],
-  properties: {
-    score: {
-      type: "number"
-    },
-    level: {
-      $ref: "#/$defs/level"
-    },
-    whitelisted: {
-      type: "boolean"
-    },
-    whitelists: {
-      type: "array",
-      items: {
-        $ref: "#/$defs/whitelist"
-      },
-      default: []
-    },
-    observables: {
-      type: "object",
-      additionalProperties: {
-        $ref: "#/$defs/observable"
-      },
-      default: {}
-    },
-    checks: {
-      type: "object",
-      additionalProperties: {
-        type: "array",
-        items: {
-          $ref: "#/$defs/check"
-        },
-        default: []
-      },
-      default: {}
-    },
-    checks_by_level: {
-      type: "object",
-      additionalProperties: {
-        type: "array",
-        items: {
-          type: "string"
-        },
-        default: []
-      },
-      default: {}
-    },
-    threat_intels: {
-      type: "object",
-      additionalProperties: {
-        $ref: "#/$defs/threat_intel"
-      },
-      default: {}
-    },
-    enrichments: {
-      type: "object",
-      additionalProperties: {
-        $ref: "#/$defs/enrichment"
-      },
-      default: {}
-    },
-    containers: {
-      type: "object",
-      additionalProperties: {
-        $ref: "#/$defs/container"
-      },
-      default: {}
-    },
-    stats: {
-      $ref: "#/$defs/statistics"
-    },
-    stats_checks: {
-      $ref: "#/$defs/stats_checks"
-    },
-    data_extraction: {
-      $ref: "#/$defs/data_extraction"
-    }
-  },
   $defs: {
-    level: {
-      type: "string",
-      enum: [
-        "NONE",
-        "TRUSTED",
-        "INFO",
-        "SAFE",
-        "NOTABLE",
-        "SUSPICIOUS",
-        "MALICIOUS"
-      ],
-      description: "Security level classification from NONE (lowest) to MALICIOUS (highest)."
-    },
-    relationship_direction: {
-      type: "string",
-      enum: [
-        "outbound",
-        "inbound",
-        "bidirectional"
-      ],
-      description: "Direction of a relationship between observables."
-    },
-    score_policy: {
-      type: "string",
-      enum: [
-        "auto",
-        "manual"
-      ],
-      description: "Score computation policy: 'auto' calculates from level, 'manual' uses explicit score."
-    },
-    score_mode: {
-      type: "string",
-      enum: [
-        "max",
-        "sum"
-      ],
-      description: "Score aggregation mode: 'max' takes highest score, 'sum' adds all scores."
-    },
-    whitelist: {
-      type: "object",
-      required: [
-        "identifier",
-        "name"
-      ],
+    Check: {
+      description: "Represents a verification step in the investigation.\n\nA check validates a specific aspect of the data under investigation\nand contributes to the overall investigation score.",
       properties: {
-        identifier: {
-          type: "string"
-        },
-        name: {
-          type: "string"
-        },
-        justification: {
-          type: [
-            "string",
-            "null"
-          ]
-        }
-      },
-      additionalProperties: false
-    },
-    relationship: {
-      type: "object",
-      required: [
-        "target_key",
-        "relationship_type",
-        "direction"
-      ],
-      properties: {
-        target_key: {
+        check_id: {
+          title: "Check Id",
           type: "string"
         },
-        relationship_type: {
-          type: "string",
-          description: "Relationship label; defaults to related-to.",
-          examples: [
-            "related-to"
-          ]
-        },
-        direction: {
-          $ref: "#/$defs/relationship_direction"
-        }
-      },
-      additionalProperties: false
-    },
-    observable: {
-      type: "object",
-      required: [
-        "key",
-        "type",
-        "value",
-        "internal",
-        "whitelisted",
-        "comment",
-        "extra",
-        "score",
-        "level",
-        "relationships",
-        "threat_intels",
-        "generated_by_checks"
-      ],
-      properties: {
-        key: {
+        scope: {
+          title: "Scope",
           type: "string"
         },
-        type: {
-          type: "string",
-          description: "Observable type (e.g., ipv4-addr, url). Custom values are allowed.",
-          examples: [
-            "ipv4-addr",
-            "ipv6-addr",
-            "domain-name",
-            "url",
-            "network-traffic",
-            "mac-addr",
-            "file",
-            "directory",
-            "email-addr",
-            "email-message",
-            "email-mime-part",
-            "user-account",
-            "process",
-            "software",
-            "windows-registry-key",
-            "artifact",
-            "autonomous-system",
-            "mutex",
-            "x509-certificate"
-          ]
-        },
-        value: {
+        description: {
+          title: "Description",
           type: "string"
         },
-        internal: {
-          type: "boolean"
-        },
-        whitelisted: {
-          type: "boolean"
-        },
         comment: {
+          title: "Comment",
           type: "string"
         },
         extra: {
-          type: [
-            "object",
-            "null"
-          ],
-          default: {}
+          additionalProperties: true,
+          title: "Extra",
+          type: "object"
         },
         score: {
+          title: "Score",
           type: "number"
         },
         level: {
-          $ref: "#/$defs/level"
-        },
-        relationships: {
-          type: "array",
-          items: {
-            $ref: "#/$defs/relationship"
-          },
-          default: []
+          $ref: "#/$defs/Level"
         },
-        threat_intels: {
-          type: "array",
+        observables: {
           items: {
             type: "string"
           },
-          default: []
+          title: "Observables",
+          type: "array"
         },
-        generated_by_checks: {
-          type: "array",
-          items: {
-            type: "string"
-          },
-          default: []
+        score_policy: {
+          $ref: "#/$defs/CheckScorePolicy",
+          default: "auto"
+        },
+        key: {
+          title: "Key",
+          type: "string"
         }
       },
-      additionalProperties: false
-    },
-    check: {
-      type: "object",
       required: [
-        "key",
         "check_id",
         "scope",
         "description",
@@ -291,342 +60,603 @@ var cyvest_schema_default = {
         "extra",
         "score",
         "level",
-        "score_policy",
-        "observables"
+        "observables",
+        "key"
+      ],
+      title: "Check",
+      type: "object"
+    },
+    CheckScorePolicy: {
+      description: "Controls how a check reacts to linked observables.",
+      enum: [
+        "auto",
+        "manual"
       ],
+      title: "CheckScorePolicy",
+      type: "string"
+    },
+    Container: {
+      additionalProperties: false,
+      description: "Groups checks and sub-containers for hierarchical organization.\n\nContainers allow structuring the investigation into logical sections\nwith aggregated scores and levels.",
       properties: {
-        key: {
+        path: {
+          title: "Path",
           type: "string"
         },
-        check_id: {
+        description: {
+          default: "",
+          title: "Description",
           type: "string"
         },
-        scope: {
-          type: "string"
+        checks: {
+          items: {
+            type: "string"
+          },
+          title: "Checks",
+          type: "array"
         },
-        description: {
-          type: "string"
+        sub_containers: {
+          additionalProperties: {
+            $ref: "#/$defs/Container"
+          },
+          title: "Sub Containers",
+          type: "object"
         },
-        comment: {
+        key: {
+          title: "Key",
           type: "string"
         },
-        extra: {
-          type: [
-            "object",
-            "null"
-          ],
-          default: {}
-        },
-        score: {
+        aggregated_score: {
+          readOnly: true,
+          title: "Aggregated Score",
           type: "number"
         },
-        level: {
-          $ref: "#/$defs/level"
-        },
-        score_policy: {
-          $ref: "#/$defs/score_policy"
-        },
-        observables: {
-          type: "array",
-          items: {
-            type: "string"
-          },
-          default: []
+        aggregated_level: {
+          $ref: "#/$defs/Level",
+          description: "Calculate the aggregated level from the aggregated score.\n\nReturns:\n    Level based on aggregated score",
+          readOnly: true
         }
       },
-      additionalProperties: false
-    },
-    threat_intel: {
-      type: "object",
       required: [
+        "path",
+        "checks",
+        "sub_containers",
         "key",
-        "source",
-        "observable_key",
-        "comment",
-        "extra",
-        "score",
-        "level",
-        "taxonomies"
+        "aggregated_score",
+        "aggregated_level"
       ],
+      title: "Container",
+      type: "object"
+    },
+    DataExtractionSchema: {
+      additionalProperties: false,
+      description: "Schema for data extraction metadata.",
       properties: {
-        key: {
-          type: "string"
+        root_type: {
+          anyOf: [
+            {
+              type: "string"
+            },
+            {
+              type: "null"
+            }
+          ],
+          default: null,
+          description: "Root observable type used during data extraction.",
+          title: "Root Type"
         },
-        source: {
+        score_mode: {
+          $ref: "#/$defs/ScoreMode",
+          description: "Score aggregation mode: 'max' takes highest score, 'sum' adds all scores."
+        }
+      },
+      required: [
+        "score_mode"
+      ],
+      title: "DataExtractionSchema",
+      type: "object"
+    },
+    Enrichment: {
+      description: "Represents structured data enrichment for the investigation.\n\nEnrichments store arbitrary structured data that provides additional\ncontext but doesn't directly contribute to scoring.",
+      properties: {
+        name: {
+          title: "Name",
           type: "string"
         },
-        observable_key: {
-          type: "string"
+        data: {
+          title: "Data"
         },
-        comment: {
+        context: {
+          title: "Context",
           type: "string"
         },
-        extra: {
-          type: [
-            "object",
-            "null"
-          ],
-          default: {}
-        },
-        score: {
-          type: "number"
-        },
-        level: {
-          $ref: "#/$defs/level"
-        },
-        taxonomies: {
-          type: "array",
-          items: {
-            type: "object"
-          },
-          default: []
+        key: {
+          title: "Key",
+          type: "string"
         }
       },
-      additionalProperties: false
-    },
-    enrichment: {
-      type: "object",
       required: [
-        "key",
         "name",
         "data",
-        "context"
+        "context",
+        "key"
       ],
+      title: "Enrichment",
+      type: "object"
+    },
+    InvestigationWhitelist: {
+      description: "Represents a whitelist entry on an investigation.",
       properties: {
-        key: {
+        identifier: {
+          minLength: 1,
+          title: "Identifier",
           type: "string"
         },
         name: {
+          minLength: 1,
+          title: "Name",
           type: "string"
         },
-        data: {
-          type: "object"
-        },
-        context: {
-          type: "string"
+        justification: {
+          anyOf: [
+            {
+              type: "string"
+            },
+            {
+              type: "null"
+            }
+          ],
+          default: null,
+          title: "Justification"
         }
       },
-      additionalProperties: false
-    },
-    container: {
-      type: "object",
       required: [
-        "key",
-        "path",
-        "description",
-        "checks",
-        "sub_containers",
-        "aggregated_score",
-        "aggregated_level"
+        "identifier",
+        "name"
+      ],
+      title: "InvestigationWhitelist",
+      type: "object"
+    },
+    Level: {
+      description: "Security level classification for checks, observables, and threat intelligence.\n\nLevels are ordered from lowest (NONE) to highest (MALICIOUS) severity.",
+      enum: [
+        "NONE",
+        "TRUSTED",
+        "INFO",
+        "SAFE",
+        "NOTABLE",
+        "SUSPICIOUS",
+        "MALICIOUS"
       ],
+      title: "Level",
+      type: "string"
+    },
+    Observable: {
+      description: "Represents a cyber observable (IP, URL, domain, hash, etc.).\n\nObservables can be linked to threat intelligence, checks, and other observables\nthrough relationships.",
       properties: {
-        key: {
+        type: {
+          title: "Type",
           type: "string"
         },
-        path: {
+        value: {
+          title: "Value",
           type: "string"
         },
-        description: {
+        internal: {
+          title: "Internal",
+          type: "boolean"
+        },
+        whitelisted: {
+          title: "Whitelisted",
+          type: "boolean"
+        },
+        comment: {
+          title: "Comment",
           type: "string"
         },
-        checks: {
-          type: "array",
+        extra: {
+          additionalProperties: true,
+          title: "Extra",
+          type: "object"
+        },
+        score: {
+          title: "Score",
+          type: "number"
+        },
+        level: {
+          $ref: "#/$defs/Level"
+        },
+        threat_intels: {
           items: {
             type: "string"
           },
-          default: []
+          title: "Threat Intels",
+          type: "array"
         },
-        sub_containers: {
-          type: "object",
-          additionalProperties: {
-            $ref: "#/$defs/container"
+        relationships: {
+          items: {
+            $ref: "#/$defs/Relationship"
           },
-          default: {}
+          title: "Relationships",
+          type: "array"
         },
-        aggregated_score: {
-          type: "number"
+        key: {
+          title: "Key",
+          type: "string"
         },
-        aggregated_level: {
-          $ref: "#/$defs/level"
+        generated_by_checks: {
+          description: "Checks that generated this observable.",
+          items: {
+            type: "string"
+          },
+          readOnly: true,
+          title: "Generated By Checks",
+          type: "array"
         }
       },
-      additionalProperties: false
+      required: [
+        "type",
+        "value",
+        "internal",
+        "whitelisted",
+        "comment",
+        "extra",
+        "score",
+        "level",
+        "threat_intels",
+        "relationships",
+        "key",
+        "generated_by_checks"
+      ],
+      title: "Observable",
+      type: "object"
     },
-    statistics: {
-      type: "object",
+    Relationship: {
+      description: "Represents a relationship between observables.",
+      properties: {
+        target_key: {
+          title: "Target Key",
+          type: "string"
+        },
+        relationship_type: {
+          title: "Relationship Type",
+          type: "string"
+        },
+        direction: {
+          $ref: "#/$defs/RelationshipDirection"
+        }
+      },
       required: [
-        "total_observables",
-        "internal_observables",
-        "external_observables",
-        "whitelisted_observables",
-        "observables_by_type",
-        "observables_by_level",
-        "observables_by_type_and_level",
-        "total_checks",
-        "applied_checks",
-        "checks_by_scope",
-        "checks_by_level",
-        "total_threat_intel",
-        "threat_intel_by_source",
-        "threat_intel_by_level",
-        "total_containers"
+        "target_key",
+        "relationship_type",
+        "direction"
+      ],
+      title: "Relationship",
+      type: "object"
+    },
+    RelationshipDirection: {
+      description: "Direction of a relationship between observables.",
+      enum: [
+        "outbound",
+        "inbound",
+        "bidirectional"
       ],
+      title: "RelationshipDirection",
+      type: "string"
+    },
+    ScoreMode: {
+      description: "Score calculation mode for observables.",
+      enum: [
+        "max",
+        "sum"
+      ],
+      title: "ScoreMode",
+      type: "string"
+    },
+    StatisticsSchema: {
+      additionalProperties: false,
+      description: "Schema for investigation statistics.\n\nMirrors the output of `InvestigationStats.get_summary()`.",
       properties: {
         total_observables: {
-          type: "integer",
-          minimum: 0
+          minimum: 0,
+          title: "Total Observables",
+          type: "integer"
         },
         internal_observables: {
-          type: "integer",
-          minimum: 0
+          minimum: 0,
+          title: "Internal Observables",
+          type: "integer"
         },
         external_observables: {
-          type: "integer",
-          minimum: 0
+          minimum: 0,
+          title: "External Observables",
+          type: "integer"
         },
         whitelisted_observables: {
-          type: "integer",
-          minimum: 0
+          minimum: 0,
+          title: "Whitelisted Observables",
+          type: "integer"
         },
         observables_by_type: {
-          type: "object",
           additionalProperties: {
-            type: "integer",
-            minimum: 0
+            minimum: 0,
+            type: "integer"
           },
-          default: {}
+          title: "Observables By Type",
+          type: "object"
         },
         observables_by_level: {
-          type: "object",
           additionalProperties: {
-            type: "integer",
-            minimum: 0
+            minimum: 0,
+            type: "integer"
           },
-          default: {}
+          title: "Observables By Level",
+          type: "object"
         },
         observables_by_type_and_level: {
-          type: "object",
           additionalProperties: {
-            type: "object",
             additionalProperties: {
-              type: "integer",
-              minimum: 0
+              minimum: 0,
+              type: "integer"
             },
-            default: {}
+            type: "object"
           },
-          default: {}
+          title: "Observables By Type And Level",
+          type: "object"
         },
         total_checks: {
-          type: "integer",
-          minimum: 0
+          minimum: 0,
+          title: "Total Checks",
+          type: "integer"
         },
         applied_checks: {
-          type: "integer",
-          minimum: 0
+          minimum: 0,
+          title: "Applied Checks",
+          type: "integer"
         },
         checks_by_scope: {
-          type: "object",
           additionalProperties: {
-            type: "integer",
-            minimum: 0
+            minimum: 0,
+            type: "integer"
           },
-          default: {}
+          title: "Checks By Scope",
+          type: "object"
         },
         checks_by_level: {
-          type: "object",
           additionalProperties: {
-            type: "integer",
-            minimum: 0
+            minimum: 0,
+            type: "integer"
           },
-          default: {}
+          title: "Checks By Level",
+          type: "object"
         },
         total_threat_intel: {
-          type: "integer",
-          minimum: 0
+          minimum: 0,
+          title: "Total Threat Intel",
+          type: "integer"
         },
         threat_intel_by_source: {
-          type: "object",
           additionalProperties: {
-            type: "integer",
-            minimum: 0
+            minimum: 0,
+            type: "integer"
           },
-          default: {}
+          title: "Threat Intel By Source",
+          type: "object"
         },
         threat_intel_by_level: {
-          type: "object",
           additionalProperties: {
-            type: "integer",
-            minimum: 0
+            minimum: 0,
+            type: "integer"
           },
-          default: {}
+          title: "Threat Intel By Level",
+          type: "object"
         },
         total_containers: {
-          type: "integer",
-          minimum: 0
+          minimum: 0,
+          title: "Total Containers",
+          type: "integer"
         }
       },
-      additionalProperties: false
-    },
-    stats_checks: {
-      type: "object",
       required: [
-        "checks",
-        "applied"
+        "total_observables",
+        "internal_observables",
+        "external_observables",
+        "whitelisted_observables",
+        "total_checks",
+        "applied_checks",
+        "total_threat_intel",
+        "total_containers"
       ],
+      title: "StatisticsSchema",
+      type: "object"
+    },
+    StatsChecksSchema: {
+      additionalProperties: false,
+      description: "Schema for check statistics summary.",
       properties: {
         checks: {
-          type: "integer",
-          minimum: 0
+          minimum: 0,
+          title: "Checks",
+          type: "integer"
         },
         applied: {
-          type: "integer",
-          minimum: 0
+          minimum: 0,
+          title: "Applied",
+          type: "integer"
         }
       },
-      additionalProperties: false
-    },
-    data_extraction: {
-      type: "object",
       required: [
-        "root_type",
-        "score_mode"
+        "checks",
+        "applied"
       ],
+      title: "StatsChecksSchema",
+      type: "object"
+    },
+    ThreatIntel: {
+      description: "Represents threat intelligence from an external source.\n\nThreat intelligence provides verdicts about observables from sources\nlike VirusTotal, URLScan.io, etc.",
       properties: {
-        root_type: {
-          type: [
-            "string",
-            "null"
-          ],
-          description: "Root observable type used during data extraction.",
-          examples: [
-            "ipv4-addr",
-            "ipv6-addr",
-            "domain-name",
-            "url",
-            "network-traffic",
-            "mac-addr",
-            "file",
-            "directory",
-            "email-addr",
-            "email-message",
-            "email-mime-part",
-            "user-account",
-            "process",
-            "software",
-            "windows-registry-key",
-            "artifact",
-            "autonomous-system",
-            "mutex",
-            "x509-certificate"
-          ]
+        source: {
+          title: "Source",
+          type: "string"
         },
-        score_mode: {
-          $ref: "#/$defs/score_mode"
+        observable_key: {
+          title: "Observable Key",
+          type: "string"
+        },
+        comment: {
+          title: "Comment",
+          type: "string"
+        },
+        extra: {
+          additionalProperties: true,
+          title: "Extra",
+          type: "object"
+        },
+        score: {
+          title: "Score",
+          type: "number"
+        },
+        level: {
+          $ref: "#/$defs/Level"
+        },
+        taxonomies: {
+          items: {
+            additionalProperties: true,
+            type: "object"
+          },
+          title: "Taxonomies",
+          type: "array"
+        },
+        key: {
+          title: "Key",
+          type: "string"
         }
       },
-      additionalProperties: false
+      required: [
+        "source",
+        "observable_key",
+        "comment",
+        "extra",
+        "score",
+        "level",
+        "taxonomies",
+        "key"
+      ],
+      title: "ThreatIntel",
+      type: "object"
     }
-  }
+  },
+  $id: "https://cyvest.io/schema/investigation.json",
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  additionalProperties: false,
+  description: "Schema for a complete serialized investigation.\n\nThis model describes the output of `serialize_investigation()` from\n`cyvest.io_serialization`. It is the top-level schema for exported investigations.\n\nEntity types reference the runtime models directly. When generating schemas with\n`mode='serialization'`, Pydantic respects field_serializer decorators and produces\nschemas matching the actual model_dump() output.",
+  properties: {
+    score: {
+      description: "Global investigation score.",
+      title: "Score",
+      type: "number"
+    },
+    level: {
+      $ref: "#/$defs/Level",
+      description: "Security level classification from NONE (lowest) to MALICIOUS (highest)."
+    },
+    whitelisted: {
+      description: "Whether the investigation is whitelisted.",
+      title: "Whitelisted",
+      type: "boolean"
+    },
+    whitelists: {
+      description: "List of whitelist entries applied to this investigation.",
+      items: {
+        $ref: "#/$defs/InvestigationWhitelist"
+      },
+      title: "Whitelists",
+      type: "array"
+    },
+    observables: {
+      additionalProperties: {
+        $ref: "#/$defs/Observable"
+      },
+      description: "Observables keyed by their unique key.",
+      title: "Observables",
+      type: "object"
+    },
+    checks: {
+      additionalProperties: {
+        items: {
+          $ref: "#/$defs/Check"
+        },
+        type: "array"
+      },
+      description: "Checks organized by scope.",
+      title: "Checks",
+      type: "object"
+    },
+    checks_by_level: {
+      additionalProperties: {
+        items: {
+          type: "string"
+        },
+        type: "array"
+      },
+      description: "Check keys organized by level name.",
+      title: "Checks By Level",
+      type: "object"
+    },
+    threat_intels: {
+      additionalProperties: {
+        $ref: "#/$defs/ThreatIntel"
+      },
+      description: "Threat intelligence entries keyed by their unique key.",
+      title: "Threat Intels",
+      type: "object"
+    },
+    enrichments: {
+      additionalProperties: {
+        $ref: "#/$defs/Enrichment"
+      },
+      description: "Enrichment entries keyed by their unique key.",
+      title: "Enrichments",
+      type: "object"
+    },
+    containers: {
+      additionalProperties: {
+        $ref: "#/$defs/Container"
+      },
+      description: "Containers keyed by their unique key.",
+      title: "Containers",
+      type: "object"
+    },
+    stats: {
+      $ref: "#/$defs/StatisticsSchema",
+      description: "Investigation statistics summary."
+    },
+    stats_checks: {
+      $ref: "#/$defs/StatsChecksSchema",
+      description: "Check statistics summary."
+    },
+    data_extraction: {
+      $ref: "#/$defs/DataExtractionSchema",
+      description: "Data extraction metadata."
+    }
+  },
+  required: [
+    "score",
+    "level",
+    "whitelisted",
+    "whitelists",
+    "observables",
+    "checks",
+    "checks_by_level",
+    "threat_intels",
+    "enrichments",
+    "containers",
+    "stats",
+    "stats_checks",
+    "data_extraction"
+  ],
+  title: "Cyvest Investigation",
+  type: "object"
 };
 
 // src/helpers.ts
@@ -854,9 +884,15 @@ function hasLevel(obj) {
 }
 function getEntityLevel(entity) {
   if ("aggregated_level" in entity) {
-    return entity.aggregated_level;
+    const aggregatedLevel = entity.aggregated_level;
+    if (typeof aggregatedLevel === "string" && isValidLevel(aggregatedLevel)) {
+      return aggregatedLevel;
+    }
+  }
+  if ("level" in entity && isValidLevel(entity.level)) {
+    return entity.level;
   }
-  return entity.level;
+  throw new Error("Entity does not have a valid level.");
 }
 
 // src/getters.ts