@optimizely-opal/opal-tool-ocp-sdk 1.0.0-beta.2 → 1.0.0-beta.4

package/src/types/ToolError.ts

@@ -0,0 +1,95 @@
+/**
+ * Validation error details
+ */
+export interface ValidationError {
+  field: string;
+  message: string;
+}
+
+/**
+ * Custom error class for tool functions that supports RFC 9457 Problem Details format
+ *
+ * @example
+ * ```typescript
+ * // Throw a 404 error
+ * throw new ToolError('Resource not found', 404, 'The requested task does not exist');
+ *
+ * // Throw a 400 error
+ * throw new ToolError('Invalid input', 400, 'The priority must be "low", "medium", or "high"');
+ *
+ * // Throw a 500 error (default)
+ * throw new ToolError('Database connection failed');
+ *
+ * // Throw a validation error with multiple field errors
+ * throw new ToolError('Validation failed', 400, "See 'errors' field for details.", [
+ *   { field: 'email', message: 'Invalid email format' },
+ *   { field: 'age', message: 'Must be a positive number' }
+ * ]);
+ * ```
+ */
+export class ToolError extends Error {
+  /**
+   * HTTP status code for the error response
+   */
+  public readonly status: number;
+
+  /**
+   * Detailed error description (optional)
+   */
+  public readonly detail?: string;
+
+  /**
+   * Array of validation errors (optional)
+   */
+  public readonly errors?: ValidationError[];
+
+  /**
+   * Create a new ToolError
+   *
+   * @param message - Error message (used as RFC 9457 "title" field)
+   * @param status - HTTP status code (default: 500)
+   * @param detail - Detailed error description (optional)
+   * @param errors - Array of validation errors (optional)
+   */
+  public constructor(
+    message: string,
+    status: number = 500,
+    detail?: string,
+    errors?: ValidationError[]
+  ) {
+    super(message);
+    this.name = 'ToolError';
+    this.status = status;
+    this.detail = detail;
+    this.errors = errors;
+
+    // Maintains proper stack trace for where error was thrown (V8 engines only)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, ToolError);
+    }
+  }
+
+  /**
+   * Convert error to RFC 9457 Problem Details format
+   *
+   * @param instance - URI reference identifying the specific occurrence of the problem
+   * @returns RFC 9457 compliant error object
+   */
+  public toProblemDetails(instance: string): Record<string, unknown> {
+    const problemDetails: Record<string, unknown> = {
+      title: this.message,
+      status: this.status,
+      instance
+    };
+
+    if (this.detail) {
+      problemDetails.detail = this.detail;
+    }
+
+    if (this.errors && this.errors.length > 0) {
+      problemDetails.errors = this.errors;
+    }
+
+    return problemDetails;
+  }
+}

package/src/validation/ParameterValidator.test.ts

@@ -1,5 +1,6 @@
 import { ParameterValidator } from './ParameterValidator';
 import { Parameter, ParameterType } from '../types/Models';
+import { ToolError } from '../types/ToolError';
 
 describe('ParameterValidator', () => {
   describe('validate', () => {
@@ -22,13 +23,12 @@ describe('ParameterValidator', () => {
         config: { theme: 'dark', language: 'en' }
       };
 
-      const result = ParameterValidator.validate(validParams, paramDefs);
-
-      expect(result.isValid).toBe(true);
-      expect(result.errors).toHaveLength(0);
+      expect(() => {
+        ParameterValidator.validate(validParams, paramDefs, '/test-endpoint');
+      }).not.toThrow();
     });
 
-    it('should fail validation for missing required parameters', () => {
+    it('should throw ToolError for missing required parameters', () => {
       const paramDefs = [
         new Parameter('name', ParameterType.String, 'User name', true),
         new Parameter('email', ParameterType.String, 'User email', true)
@@ -39,17 +39,27 @@ describe('ParameterValidator', () => {
         // email is missing
       };
 
-      const result = ParameterValidator.validate(params, paramDefs);
-
-      expect(result.isValid).toBe(false);
-      expect(result.errors).toHaveLength(1);
-      expect(result.errors[0]).toEqual({
-        field: 'email',
-        message: "Required parameter 'email' is missing"
-      });
+      expect(() => {
+        ParameterValidator.validate(params, paramDefs, '/test-endpoint');
+      }).toThrow(ToolError);
+
+      try {
+        ParameterValidator.validate(params, paramDefs, '/test-endpoint');
+      } catch (error) {
+        expect(error).toBeInstanceOf(ToolError);
+        const toolError = error as ToolError;
+        expect(toolError.status).toBe(400);
+        expect(toolError.message).toBe('One or more validation errors occurred.');
+        expect(toolError.detail).toBe("See 'errors' field for details.");
+        expect(toolError.errors).toHaveLength(1);
+        expect(toolError.errors).toEqual([{
+          field: 'email',
+          message: "Required parameter 'email' is missing"
+        }]);
+      }
     });
 
-    it('should fail validation for wrong parameter types', () => {
+    it('should throw ToolError for wrong parameter types', () => {
       const paramDefs = [
         new Parameter('name', ParameterType.String, 'User name', true),
         new Parameter('age', ParameterType.Integer, 'User age', true),
@@ -66,42 +76,64 @@ describe('ParameterValidator', () => {
         config: 'invalid' // should be object
       };
 
-      const result = ParameterValidator.validate(invalidParams, paramDefs);
-
-      expect(result.isValid).toBe(false);
-      expect(result.errors).toHaveLength(5);
+      try {
+        ParameterValidator.validate(invalidParams, paramDefs, '/test-endpoint');
+        fail('Should have thrown ToolError');
+      } catch (error) {
+        expect(error).toBeInstanceOf(ToolError);
+        const toolError = error as ToolError;
+        expect(toolError.status).toBe(400);
+        expect(toolError.errors).toHaveLength(5);
 
-      expect(result.errors[0].field).toBe('name');
-      expect(result.errors[0].message).toContain('must be a string');
+        expect(toolError.errors![0].field).toBe('name');
+        expect(toolError.errors![0].message).toContain('must be a string');
 
-      expect(result.errors[1].field).toBe('age');
-      expect(result.errors[1].message).toContain('must be an integer');
+        expect(toolError.errors![1].field).toBe('age');
+        expect(toolError.errors![1].message).toContain('must be an integer');
 
-      expect(result.errors[2].field).toBe('active');
-      expect(result.errors[2].message).toContain('must be a boolean');
+        expect(toolError.errors![2].field).toBe('active');
+        expect(toolError.errors![2].message).toContain('must be a boolean');
 
-      expect(result.errors[3].field).toBe('tags');
-      expect(result.errors[3].message).toContain('must be an array');
+        expect(toolError.errors![3].field).toBe('tags');
+        expect(toolError.errors![3].message).toContain('must be an array');
 
-      expect(result.errors[4].field).toBe('config');
-      expect(result.errors[4].message).toContain('must be an object');
+        expect(toolError.errors![4].field).toBe('config');
+        expect(toolError.errors![4].message).toContain('must be an object');
+      }
     });
 
-    it('should handle null/undefined parameters correctly', () => {
+    it('should throw ToolError when params is null with required parameters', () => {
       const paramDefs = [
         new Parameter('required', ParameterType.String, 'Required param', true),
         new Parameter('optional', ParameterType.String, 'Optional param', false)
       ];
 
-      const result1 = ParameterValidator.validate(null, paramDefs);
-      expect(result1.isValid).toBe(false);
-      expect(result1.errors).toHaveLength(1);
-      expect(result1.errors[0].field).toBe('required');
+      try {
+        ParameterValidator.validate(null, paramDefs, '/test-endpoint');
+        fail('Should have thrown ToolError');
+      } catch (error) {
+        expect(error).toBeInstanceOf(ToolError);
+        const toolError = error as ToolError;
+        expect(toolError.errors).toHaveLength(1);
+        expect(toolError.errors![0].field).toBe('required');
+      }
+    });
 
-      const result2 = ParameterValidator.validate(undefined, paramDefs);
-      expect(result2.isValid).toBe(false);
-      expect(result2.errors).toHaveLength(1);
-      expect(result2.errors[0].field).toBe('required');
+    it('should throw ToolError when params is undefined with required parameters', () => {
+      const paramDefs = [
+        new Parameter('required', ParameterType.String, 'Required param', true),
+        new Parameter('optional', ParameterType.String, 'Optional param', false)
+      ];
+
+      try {
+        ParameterValidator.validate(undefined, paramDefs, '/test-endpoint');
+        fail('Should have thrown ToolError');
+      } catch (error) {
+        expect(error).toBeInstanceOf(ToolError);
+        const toolError = error as ToolError;
+        expect(toolError.errors).toHaveLength(1);
+        expect(toolError.errors![0].field).toBe('required');
+      }
     });
 
     it('should allow optional parameters to be missing', () => {
@@ -115,10 +147,9 @@ describe('ParameterValidator', () => {
         // age is optional and missing
       };
 
-      const result = ParameterValidator.validate(params, paramDefs);
-
-      expect(result.isValid).toBe(true);
-      expect(result.errors).toHaveLength(0);
+      expect(() => {
+        ParameterValidator.validate(params, paramDefs, '/test-endpoint');
+      }).not.toThrow();
     });
 
     it('should distinguish between integer and number types', () => {
@@ -132,210 +163,206 @@ describe('ParameterValidator', () => {
         score: 85.5  // number is fine
       };
 
-      const result1 = ParameterValidator.validate(params1, paramDefs);
-      expect(result1.isValid).toBe(false);
-      expect(result1.errors).toHaveLength(1);
-      expect(result1.errors[0].field).toBe('count');
-      expect(result1.errors[0].message).toContain('must be an integer');
+      try {
+        ParameterValidator.validate(params1, paramDefs, '/test-endpoint');
+        fail('Should have thrown ToolError');
+      } catch (error) {
+        expect(error).toBeInstanceOf(ToolError);
+        const toolError = error as ToolError;
+        expect(toolError.errors).toHaveLength(1);
+        expect(toolError.errors![0].field).toBe('count');
+        expect(toolError.errors![0].message).toContain('must be an integer');
+      }
 
       const params2 = {
         count: 25,   // integer is fine
         score: 85.5  // number is fine
       };
 
-      const result2 = ParameterValidator.validate(params2, paramDefs);
-      expect(result2.isValid).toBe(true);
-      expect(result2.errors).toHaveLength(0);
+      expect(() => {
+        ParameterValidator.validate(params2, paramDefs, '/test-endpoint');
+      }).not.toThrow();
     });
 
     it('should handle array vs object distinction', () => {
       const paramDefs = [
-        new Parameter('tags', ParameterType.List, 'Tag list', true),
-        new Parameter('config', ParameterType.Dictionary, 'Config object', true)
+        new Parameter('tags', ParameterType.List, 'Tags', true),
+        new Parameter('config', ParameterType.Dictionary, 'Config', true)
       ];
 
       const params = {
-        tags: { 0: 'tag1', 1: 'tag2' }, // object that looks like array
-        config: ['key1', 'key2'] // array instead of object
+        tags: { key: 'value' }, // should be array, not object
+        config: ['item1', 'item2'] // should be object, not array
       };
 
-      const result = ParameterValidator.validate(params, paramDefs);
-      expect(result.isValid).toBe(false);
-      expect(result.errors).toHaveLength(2);
-
-      expect(result.errors[0].field).toBe('tags');
-      expect(result.errors[0].message).toContain('must be an array');
-
-      expect(result.errors[1].field).toBe('config');
-      expect(result.errors[1].message).toContain('must be an object');
+      try {
+        ParameterValidator.validate(params, paramDefs, '/test-endpoint');
+        fail('Should have thrown ToolError');
+      } catch (error) {
+        expect(error).toBeInstanceOf(ToolError);
+        const toolError = error as ToolError;
+        expect(toolError.errors).toHaveLength(2);
+      }
     });
 
     it('should handle null values for optional parameters', () => {
       const paramDefs = [
         new Parameter('name', ParameterType.String, 'User name', true),
-        new Parameter('age', ParameterType.Integer, 'User age', false)
+        new Parameter('nickname', ParameterType.String, 'Nickname', false)
       ];
 
       const params = {
         name: 'John Doe',
-        age: null // null for optional parameter should be allowed
+        nickname: null // optional param can be null
       };
 
-      const result = ParameterValidator.validate(params, paramDefs);
-      expect(result.isValid).toBe(true);
-      expect(result.errors).toHaveLength(0);
+      expect(() => {
+        ParameterValidator.validate(params, paramDefs, '/test-endpoint');
+      }).not.toThrow();
     });
 
     it('should handle edge cases for number validation', () => {
       const paramDefs = [
-        new Parameter('score', ParameterType.Number, 'Score value', true)
+        new Parameter('value', ParameterType.Number, 'Number value', true)
       ];
 
-      // Test NaN
-      const params1 = { score: NaN };
-      const result1 = ParameterValidator.validate(params1, paramDefs);
-      expect(result1.isValid).toBe(false);
-      expect(result1.errors[0].message).toContain('must be a number');
-
-      // Test Infinity
-      const params2 = { score: Infinity };
-      const result2 = ParameterValidator.validate(params2, paramDefs);
-      expect(result2.isValid).toBe(true);
-      expect(result2.errors).toHaveLength(0);
-
-      // Test negative numbers
-      const params3 = { score: -42.5 };
-      const result3 = ParameterValidator.validate(params3, paramDefs);
-      expect(result3.isValid).toBe(true);
-      expect(result3.errors).toHaveLength(0);
+      // NaN should fail
+      try {
+        ParameterValidator.validate({ value: NaN }, paramDefs, '/test-endpoint');
+        fail('Should have thrown ToolError for NaN');
+      } catch (error) {
+        expect(error).toBeInstanceOf(ToolError);
+      }
+
+      // Infinity should pass (it's a number)
+      expect(() => {
+        ParameterValidator.validate({ value: Infinity }, paramDefs, '/test-endpoint');
+      }).not.toThrow();
+
+      // Negative numbers should pass
+      expect(() => {
+        ParameterValidator.validate({ value: -42.5 }, paramDefs, '/test-endpoint');
+      }).not.toThrow();
     });
 
     it('should handle edge cases for integer validation', () => {
       const paramDefs = [
-        new Parameter('count', ParameterType.Integer, 'Item count', true)
+        new Parameter('count', ParameterType.Integer, 'Count', true)
       ];
 
-      // Test negative integers
-      const params1 = { count: -5 };
-      const result1 = ParameterValidator.validate(params1, paramDefs);
-      expect(result1.isValid).toBe(true);
-      expect(result1.errors).toHaveLength(0);
-
-      // Test zero
-      const params2 = { count: 0 };
-      const result2 = ParameterValidator.validate(params2, paramDefs);
-      expect(result2.isValid).toBe(true);
-      expect(result2.errors).toHaveLength(0);
-
-      // Test very large integers
-      const params3 = { count: Number.MAX_SAFE_INTEGER };
-      const result3 = ParameterValidator.validate(params3, paramDefs);
-      expect(result3.isValid).toBe(true);
-      expect(result3.errors).toHaveLength(0);
+      // Zero should pass
+      expect(() => {
+        ParameterValidator.validate({ count: 0 }, paramDefs, '/test-endpoint');
+      }).not.toThrow();
+
+      // Negative integer should pass
+      expect(() => {
+        ParameterValidator.validate({ count: -10 }, paramDefs, '/test-endpoint');
+      }).not.toThrow();
     });
 
     it('should handle empty arrays and objects', () => {
       const paramDefs = [
-        new Parameter('tags', ParameterType.List, 'Tag list', true),
-        new Parameter('config', ParameterType.Dictionary, 'Config object', true)
+        new Parameter('tags', ParameterType.List, 'Tags', true),
+        new Parameter('config', ParameterType.Dictionary, 'Config', true)
       ];
 
       const params = {
-        tags: [], // empty array should be valid
-        config: {} // empty object should be valid
+        tags: [],
+        config: {}
       };
 
-      const result = ParameterValidator.validate(params, paramDefs);
-      expect(result.isValid).toBe(true);
-      expect(result.errors).toHaveLength(0);
+      expect(() => {
+        ParameterValidator.validate(params, paramDefs, '/test-endpoint');
+      }).not.toThrow();
     });
 
     it('should handle special string values', () => {
       const paramDefs = [
-        new Parameter('text', ParameterType.String, 'Text value', true)
+        new Parameter('value', ParameterType.String, 'String value', true)
       ];
 
-      // Test empty string
-      const params1 = { text: '' };
-      const result1 = ParameterValidator.validate(params1, paramDefs);
-      expect(result1.isValid).toBe(true);
-      expect(result1.errors).toHaveLength(0);
-
-      // Test string with special characters
-      const params2 = { text: 'Hello\nWorld\t!' };
-      const result2 = ParameterValidator.validate(params2, paramDefs);
-      expect(result2.isValid).toBe(true);
-      expect(result2.errors).toHaveLength(0);
+      // Empty string should pass
+      expect(() => {
+        ParameterValidator.validate({ value: '' }, paramDefs, '/test-endpoint');
+      }).not.toThrow();
+
+      // String with only whitespace should pass
+      expect(() => {
+        ParameterValidator.validate({ value: '   ' }, paramDefs, '/test-endpoint');
+      }).not.toThrow();
     });
 
-    it('should handle multiple validation errors', () => {
+    it('should collect multiple validation errors', () => {
       const paramDefs = [
-        new Parameter('name', ParameterType.String, 'User name', true),
-        new Parameter('age', ParameterType.Integer, 'User age', true),
-        new Parameter('email', ParameterType.String, 'User email', true)
+        new Parameter('name', ParameterType.String, 'Name', true),
+        new Parameter('age', ParameterType.Integer, 'Age', true),
+        new Parameter('email', ParameterType.String, 'Email', true)
       ];
 
       const params = {
-        name: 123, // wrong type
-        age: '25' // wrong type
+        // name is missing
+        age: 'invalid' // wrong type
         // email is missing
       };
 
-      const result = ParameterValidator.validate(params, paramDefs);
-      expect(result.isValid).toBe(false);
-      expect(result.errors).toHaveLength(3);
-
-      expect(result.errors.some((e) => e.field === 'name')).toBe(true);
-      expect(result.errors.some((e) => e.field === 'age')).toBe(true);
-      expect(result.errors.some((e) => e.field === 'email')).toBe(true);
+      try {
+        ParameterValidator.validate(params, paramDefs, '/test-endpoint');
+        fail('Should have thrown ToolError');
+      } catch (error) {
+        expect(error).toBeInstanceOf(ToolError);
+        const toolError = error as ToolError;
+        expect(toolError.errors).toHaveLength(3);
+
+        expect(toolError.errors!.some((e) => e.field === 'name')).toBe(true);
+        expect(toolError.errors!.some((e) => e.field === 'age')).toBe(true);
+        expect(toolError.errors!.some((e) => e.field === 'email')).toBe(true);
+      }
     });
 
     it('should handle tools with no parameter definitions', () => {
-      const result = ParameterValidator.validate({ someParam: 'value' }, []);
-      expect(result.isValid).toBe(true);
-      expect(result.errors).toHaveLength(0);
+      expect(() => {
+        ParameterValidator.validate({ anyParam: 'value' }, [], '/test-endpoint');
+      }).not.toThrow();
     });
 
     it('should handle extra parameters not in definition', () => {
       const paramDefs = [
-        new Parameter('name', ParameterType.String, 'User name', true)
+        new Parameter('name', ParameterType.String, 'Name', true)
       ];
 
       const params = {
-        name: 'John Doe',
-        extraParam: 'should be ignored'
+        name: 'John',
+        extraParam: 'ignored', // not in definition
+        anotherExtra: 123
       };
 
-      const result = ParameterValidator.validate(params, paramDefs);
-      expect(result.isValid).toBe(true);
-      expect(result.errors).toHaveLength(0);
+      // Extra parameters should be ignored
+      expect(() => {
+        ParameterValidator.validate(params, paramDefs, '/test-endpoint');
+      }).not.toThrow();
     });
 
     it('should handle nested objects and arrays', () => {
       const paramDefs = [
-        new Parameter('config', ParameterType.Dictionary, 'Config object', true),
-        new Parameter('matrix', ParameterType.List, 'Matrix data', true)
+        new Parameter('config', ParameterType.Dictionary, 'Config', true),
+        new Parameter('items', ParameterType.List, 'Items', true)
       ];
 
       const params = {
         config: {
           nested: {
-            deep: {
-              value: 'test'
+            deeply: {
+              nested: 'value'
             }
-          },
-          array: [1, 2, 3]
+          }
         },
-        matrix: [
-          [1, 2, 3],
-          [4, 5, 6],
-          { nested: 'object in array' }
-        ]
+        items: [1, 2, [3, 4, [5, 6]]]
       };
 
-      const result = ParameterValidator.validate(params, paramDefs);
-      expect(result.isValid).toBe(true);
-      expect(result.errors).toHaveLength(0);
+      expect(() => {
+        ParameterValidator.validate(params, paramDefs, '/test-endpoint');
+      }).not.toThrow();
     });
   });
 });

package/src/validation/ParameterValidator.ts

@@ -1,20 +1,5 @@
 import { Parameter, ParameterType } from '../types/Models';
-
-/**
- * Validation error details
- */
-export interface ValidationError {
-  field: string;
-  message: string;
-}
-
-/**
- * Validation result
- */
-export interface ValidationResult {
-  isValid: boolean;
-  errors: ValidationError[];
-}
+import { ToolError, ValidationError } from '../types/ToolError';
 
 /**
  * Parameter validator for tool inputs
@@ -22,14 +7,18 @@ export interface ValidationResult {
 export class ParameterValidator {
   /**
    * Validate parameters against their definitions
+   * Throws ToolError with status 400 if validation fails
+   *
    * @param params The actual parameters received
    * @param parameterDefinitions The expected parameter definitions
-   * @returns Validation result with any errors found
+   * @param _endpoint The endpoint being validated (reserved for future use)
+   * @throws {ToolError} When validation fails
    */
   public static validate(
     params: any,
-    parameterDefinitions: Parameter[]
-  ): ValidationResult {
+    parameterDefinitions: Parameter[],
+    _endpoint: string
+  ): void {
     const errors: ValidationError[] = [];
 
     // Validate each defined parameter
@@ -57,7 +46,15 @@ export class ParameterValidator {
       }
     }
 
-    return { isValid: errors.length === 0, errors };
+    // Throw ToolError if validation failed
+    if (errors.length > 0) {
+      throw new ToolError(
+        'One or more validation errors occurred.',
+        400,
+        "See 'errors' field for details.",
+        errors
+      );
+    }
   }
 
   /**