@orbytautomation/engine 0.2.4 → 0.4.0

package/dist/errors/ErrorCodes.d.ts

@@ -1,17 +1,43 @@
 /**
  * Orbyt Error Codes
  *
- * Stable error codes for reliable error handling and documentation.
+ * Structured error codes for the Orbyt workflow execution engine.
+ * These codes are separate from ecosystem exit codes (process-level).
+ *
+ * ARCHITECTURE:
+ * ============
+ * - Error Codes (ORB-XX-NNN): Structured diagnostic codes for detailed error identification
+ * - Exit Codes (100-509): Process-level codes from @dev-ecosystem/core for shell scripts
+ *
+ * TWO-LAYER SYSTEM:
+ * ================
+ * 1. Exit Codes (@dev-ecosystem/core): Process termination codes for the whole ecosystem
+ *    - Used by CLI, API, SDK to determine process exit status
+ *    - Example: ExitCodes.INVALID_SCHEMA (103) for schema validation failures
+ *
+ * 2. Error Codes (This file): Detailed diagnostic codes specific to Orbyt
+ *    - Used internally by engine for precise error identification
+ *    - Maps to exit codes for process termination
+ *    - Example: ORB-S-001 (unknown field) → ExitCodes.INVALID_SCHEMA
+ *
  * Format: ORB-[Category]-[Number]
  *
  * Categories:
- * - S: Schema/Structure errors
- * - V: Validation/Logic errors
- * - E: Execution errors
- * - R: Runtime errors
+ * - S: Schema/Structure errors (YAML syntax, field validation)
+ * - V: Validation/Logic errors (duplicate IDs, circular deps)
+ * - E: Execution errors (step failures, timeouts)
+ * - R: Runtime errors (file not found, permissions)
+ *
+ * ADDING NEW ERRORS:
+ * =================
+ * 1. Add error code enum value below
+ * 2. Add description in getErrorDescription()
+ * 3. Add exit code mapping in getExitCodeForError()
+ * 4. Add to appropriate error class (WorkflowError, StepError, etc.)
  *
  * @module errors
  */
+import { ExitCodes } from '@dev-ecosystem/core';
 export declare enum OrbytErrorCode {
     /** Unknown field in workflow definition */
     SCHEMA_UNKNOWN_FIELD = "ORB-S-001",
@@ -25,6 +51,8 @@ export declare enum OrbytErrorCode {
     SCHEMA_PARSE_ERROR = "ORB-S-005",
     /** Invalid field format/pattern */
     SCHEMA_INVALID_FORMAT = "ORB-S-006",
+    /** Reserved field detected (security) */
+    SCHEMA_RESERVED_FIELD = "ORB-S-007",
     /** Duplicate step ID */
     VALIDATION_DUPLICATE_ID = "ORB-V-001",
     /** Reference to non-existent step */
@@ -41,6 +69,10 @@ export declare enum OrbytErrorCode {
     VALIDATION_MISSING_INPUT = "ORB-V-007",
     /** Invalid adapter/action */
     VALIDATION_UNKNOWN_ADAPTER = "ORB-V-008",
+    /** Workflow has no steps */
+    VALIDATION_EMPTY_WORKFLOW = "ORB-V-009",
+    /** Invalid condition expression syntax */
+    VALIDATION_INVALID_CONDITION = "ORB-V-010",
     /** Step execution failed */
     EXECUTION_STEP_FAILED = "ORB-E-001",
     /** Timeout exceeded */
@@ -49,23 +81,190 @@ export declare enum OrbytErrorCode {
     EXECUTION_ADAPTER_ERROR = "ORB-E-003",
     /** Workflow cancelled */
     EXECUTION_CANCELLED = "ORB-E-004",
+    /** Step dependency failed */
+    EXECUTION_DEPENDENCY_FAILED = "ORB-E-005",
+    /** Conditional check failed */
+    EXECUTION_CONDITION_FAILED = "ORB-E-006",
     /** File not found */
     RUNTIME_FILE_NOT_FOUND = "ORB-R-001",
     /** Permission denied */
     RUNTIME_PERMISSION_DENIED = "ORB-R-002",
     /** Internal engine error */
-    RUNTIME_INTERNAL_ERROR = "ORB-R-003"
+    RUNTIME_INTERNAL_ERROR = "ORB-R-003",
+    /** Adapter not registered */
+    RUNTIME_ADAPTER_NOT_FOUND = "ORB-R-004",
+    /** Resource exhausted */
+    RUNTIME_RESOURCE_EXHAUSTED = "ORB-R-005"
 }
 /**
  * Error severity levels
+ * Used for prioritizing and determining execution control
+ *
+ * EXECUTION CONTROL BEHAVIOR:
+ * - CRITICAL/FATAL: Stop entire workflow execution immediately
+ * - ERROR/HIGH: Stop entire workflow execution (default for errors)
+ * - MEDIUM: Stop current step, attempt to continue to next step
+ * - LOW: Log warning and continue current step
+ * - WARNING: Log warning message, continue execution
+ * - INFO: Log informational message, continue execution
  */
 export declare enum ErrorSeverity {
+    /** Critical error - stop entire workflow immediately (unrecoverable) */
+    CRITICAL = "critical",
+    /** Fatal error - stop entire workflow (severe failure) */
+    FATAL = "fatal",
+    /** High severity error - stop entire workflow */
     ERROR = "error",
+    /** Medium severity - stop current step, try to continue workflow */
+    MEDIUM = "medium",
+    /** Low severity - log and continue current step */
+    LOW = "low",
+    /** Warning - log warning message, continue execution */
     WARNING = "warning",
+    /** Informational message */
     INFO = "info"
 }
 /**
  * Get human-readable category name from error code
+ *
+ * @param code - Orbyt error code
+ * @returns Category name (e.g., "Schema Error")
+ *
+ * @example
+ * ```typescript
+ * const category = getErrorCategory(OrbytErrorCode.SCHEMA_UNKNOWN_FIELD);
+ * // Returns: "Schema Error"
+ * ```
  */
 export declare function getErrorCategory(code: OrbytErrorCode): string;
+/**
+ * Get detailed description for an error code
+ * Helps users understand what went wrong
+ *
+ * @param code - Orbyt error code
+ * @returns Human-readable description
+ *
+ * @example
+ * ```typescript
+ * const desc = getErrorDescription(OrbytErrorCode.SCHEMA_UNKNOWN_FIELD);
+ * // Returns: "Workflow contains an unknown or misspelled field name"
+ * ```
+ */
+export declare function getErrorDescription(code: OrbytErrorCode): string;
+/**
+ * Map Orbyt error code to ecosystem exit code
+ * Determines which process exit code should be used
+ *
+ * @param code - Orbyt error code
+ * @returns Exit code from @dev-ecosystem/core
+ *
+ * @example
+ * ```typescript
+ * const exitCode = getExitCodeForError(OrbytErrorCode.SCHEMA_UNKNOWN_FIELD);
+ * // Returns: ExitCodes.INVALID_SCHEMA (103)
+ * ```
+ */
+export declare function getExitCodeForError(code: OrbytErrorCode): ExitCodes;
+/**
+ * Check if an error code represents a user error (fixable by changing workflow)
+ * vs system error (infrastructure, permissions, etc.)
+ *
+ * User errors are problems with the workflow definition that the user can fix.
+ * System errors are infrastructure/runtime issues outside user control.
+ *
+ * @param code - Orbyt error code
+ * @returns True if error is user-fixable
+ *
+ * @example
+ * ```typescript
+ * if (isUserError(error.code)) {
+ *   console.log('Fix your workflow definition');
+ * } else {
+ *   console.log('Contact system administrator');
+ * }
+ * ```
+ */
+export declare function isUserError(code: OrbytErrorCode): boolean;
+/**
+ * Check if an error code represents a retryable error
+ * Some errors (like timeouts, adapter failures) might succeed on retry.
+ * Others (like validation errors) will always fail.
+ *
+ * @param code - Orbyt error code
+ * @returns True if error might succeed on retry
+ *
+ * @example
+ * ```typescript
+ * if (isRetryable(error.code) && retryCount < maxRetries) {
+ *   console.log('Retrying...');
+ *   await retry();
+ * }
+ * ```
+ */
+export declare function isRetryable(code: OrbytErrorCode): boolean;
+/**
+ * Get suggested action for an error code
+ * Provides actionable guidance for users
+ *
+ * @param code - Orbyt error code
+ * @returns Suggested action to fix the error
+ *
+ * @example
+ * ```typescript
+ * const action = getSuggestedAction(OrbytErrorCode.SCHEMA_UNKNOWN_FIELD);
+ * console.log(action); // "Check field names against schema documentation"
+ * ```
+ */
+export declare function getSuggestedAction(code: OrbytErrorCode): string;
+/**
+ * Execution Control Actions
+ * Determines what action to take when error occurs
+ */
+export declare enum ExecutionControl {
+    /** Stop entire workflow execution immediately */
+    STOP_WORKFLOW = "STOP_WORKFLOW",
+    /** Stop current step, try to continue to next step */
+    STOP_STEP = "STOP_STEP",
+    /** Continue execution, just log the issue */
+    CONTINUE = "CONTINUE"
+}
+/**
+ * Get execution control action based on severity
+ * Determines whether to stop workflow, stop step, or continue
+ *
+ * @param severity - Error severity level
+ * @returns Execution control action
+ *
+ * @example
+ * ```typescript
+ * const action = getExecutionControl(ErrorSeverity.CRITICAL);
+ * // Returns: ExecutionControl.STOP_WORKFLOW
+ *
+ * const action2 = getExecutionControl(ErrorSeverity.MEDIUM);
+ * // Returns: ExecutionControl.STOP_STEP
+ * ```
+ */
+export declare function getExecutionControl(severity: ErrorSeverity): ExecutionControl;
+/**
+ * Check if severity should stop workflow execution
+ *
+ * @param severity - Error severity level
+ * @returns True if workflow should stop
+ */
+export declare function shouldStopWorkflow(severity: ErrorSeverity): boolean;
+/**
+ * Check if severity should stop step execution
+ *
+ * @param severity - Error severity level
+ * @returns True if step should stop
+ */
+export declare function shouldStopStep(severity: ErrorSeverity): boolean;
+/**
+ * Get severity level from error code
+ * Auto-determines appropriate severity for error code
+ *
+ * @param code - Orbyt error code
+ * @returns Appropriate severity level
+ */
+export declare function getSeverityForErrorCode(code: OrbytErrorCode): ErrorSeverity;
 //# sourceMappingURL=ErrorCodes.d.ts.map

package/dist/errors/ErrorCodes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ErrorCodes.d.ts","sourceRoot":"","sources":["../../src/errors/ErrorCodes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,oBAAY,cAAc;IAKxB,2CAA2C;IAC3C,oBAAoB,cAAc;IAElC,yBAAyB;IACzB,mBAAmB,cAAc;IAEjC,6BAA6B;IAC7B,oBAAoB,cAAc;IAElC,yBAAyB;IACzB,mBAAmB,cAAc;IAEjC,iCAAiC;IACjC,kBAAkB,cAAc;IAEhC,mCAAmC;IACnC,qBAAqB,cAAc;IAMnC,wBAAwB;IACxB,uBAAuB,cAAc;IAErC,qCAAqC;IACrC,uBAAuB,cAAc;IAErC,mCAAmC;IACnC,8BAA8B,cAAc;IAE5C,yBAAyB;IACzB,wBAAwB,cAAc;IAEtC,uCAAuC;IACvC,4BAA4B,cAAc;IAE1C,iCAAiC;IACjC,2BAA2B,cAAc;IAEzC,6BAA6B;IAC7B,wBAAwB,cAAc;IAEtC,6BAA6B;IAC7B,0BAA0B,cAAc;IAMxC,4BAA4B;IAC5B,qBAAqB,cAAc;IAEnC,uBAAuB;IACvB,iBAAiB,cAAc;IAE/B,oBAAoB;IACpB,uBAAuB,cAAc;IAErC,yBAAyB;IACzB,mBAAmB,cAAc;IAMjC,qBAAqB;IACrB,sBAAsB,cAAc;IAEpC,wBAAwB;IACxB,yBAAyB,cAAc;IAEvC,4BAA4B;IAC5B,sBAAsB,cAAc;CACrC;AAED;;GAEG;AACH,oBAAY,aAAa;IACvB,KAAK,UAAU;IACf,OAAO,YAAY;IACnB,IAAI,SAAS;CACd;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAM7D"}
+{"version":3,"file":"ErrorCodes.d.ts","sourceRoot":"","sources":["../../src/errors/ErrorCodes.ts"],"names":[],"mappings":"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"}