@optimizely-opal/opal-tool-ocp-sdk 1.0.0-beta.1 → 1.0.0-beta.10

package/src/types/ToolError.ts

@@ -0,0 +1,125 @@
+/**
+ * Validation error details
+ */
+export interface ValidationError {
+  field: string;
+  message: string;
+}
+
+/**
+ * Custom error class for tool functions that supports RFC 9457 Problem Details format
+ *
+ * The error message includes status code and details for better logging:
+ * - No detail: "[status] message"
+ * - With detail: "[status] message: detail"
+ * - With errors: "[status] message: field1 (error1); field2 (error2)"
+ *
+ * @example
+ * ```typescript
+ * // Throw a 404 error
+ * // Message: "[404] Resource not found: The requested task does not exist"
+ * throw new ToolError('Resource not found', 404, 'The requested task does not exist');
+ *
+ * // Throw a 400 error
+ * // Message: "[400] Invalid input: The priority must be "low", "medium", or "high""
+ * throw new ToolError('Invalid input', 400, 'The priority must be "low", "medium", or "high"');
+ *
+ * // Throw a 500 error (default)
+ * // Message: "[500] Database connection failed"
+ * throw new ToolError('Database connection failed');
+ *
+ * // Throw a validation error with multiple field errors
+ * // Message: "[400] Validation failed: email (Invalid email format); age (Must be a positive number)"
+ * 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[];
+
+  /**
+   * The title field for RFC 9457 format (same as message when no detail is provided)
+   */
+  public readonly title: string;
+
+  /**
+   * 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[]
+  ) {
+    // Build comprehensive error message for logging/debugging
+    // Format: [status] message: details
+    let fullMessage = `[${status}] ${message}`;
+
+    if (errors && errors.length > 0) {
+      // Errors take precedence: field1 (message1); field2 (message2)
+      const errorDetails = errors
+        .map((err) => `${err.field} (${err.message})`)
+        .join('; ');
+      fullMessage += `: ${errorDetails}`;
+    } else if (detail) {
+      // Include detail if no errors
+      fullMessage += `: ${detail}`;
+    }
+
+    super(fullMessage);
+    this.name = 'ToolError';
+    this.title = message;
+    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.title,
+      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

@@ -0,0 +1,371 @@
+import { ParameterValidator } from './ParameterValidator';
+import { Parameter, ParameterType } from '../types/Models';
+import { ToolError } from '../types/ToolError';
+
+describe('ParameterValidator', () => {
+  describe('validate', () => {
+    it('should pass validation for valid parameters', () => {
+      const paramDefs = [
+        new Parameter('name', ParameterType.String, 'User name', true),
+        new Parameter('age', ParameterType.Integer, 'User age', false),
+        new Parameter('score', ParameterType.Number, 'User score', false),
+        new Parameter('active', ParameterType.Boolean, 'Is active', false),
+        new Parameter('tags', ParameterType.List, 'User tags', false),
+        new Parameter('config', ParameterType.Dictionary, 'User config', false)
+      ];
+
+      const validParams = {
+        name: 'John Doe',
+        age: 25,
+        score: 85.5,
+        active: true,
+        tags: ['admin', 'user'],
+        config: { theme: 'dark', language: 'en' }
+      };
+
+      expect(() => {
+        ParameterValidator.validate(validParams, paramDefs, '/test-endpoint');
+      }).not.toThrow();
+    });
+
+    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)
+      ];
+
+      const params = {
+        name: 'John Doe'
+        // 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(
+          "[400] One or more validation errors occurred.: email (Required parameter 'email' is missing)"
+        );
+        expect(toolError.title).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 throw ToolError for wrong parameter types', () => {
+      const paramDefs = [
+        new Parameter('name', ParameterType.String, 'User name', true),
+        new Parameter('age', ParameterType.Integer, 'User age', true),
+        new Parameter('active', ParameterType.Boolean, 'Is active', true),
+        new Parameter('tags', ParameterType.List, 'User tags', true),
+        new Parameter('config', ParameterType.Dictionary, 'User config', true)
+      ];
+
+      const invalidParams = {
+        name: 123, // should be string
+        age: '25', // should be integer
+        active: 'true', // should be boolean
+        tags: 'tag1,tag2', // should be array
+        config: 'invalid' // should be object
+      };
+
+      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(toolError.errors![0].field).toBe('name');
+        expect(toolError.errors![0].message).toContain('must be a string');
+
+        expect(toolError.errors![1].field).toBe('age');
+        expect(toolError.errors![1].message).toContain('must be an integer');
+
+        expect(toolError.errors![2].field).toBe('active');
+        expect(toolError.errors![2].message).toContain('must be a boolean');
+
+        expect(toolError.errors![3].field).toBe('tags');
+        expect(toolError.errors![3].message).toContain('must be an array');
+
+        expect(toolError.errors![4].field).toBe('config');
+        expect(toolError.errors![4].message).toContain('must be an object');
+      }
+    });
+
+    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)
+      ];
+
+      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');
+      }
+    });
+
+    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', () => {
+      const paramDefs = [
+        new Parameter('name', ParameterType.String, 'User name', true),
+        new Parameter('age', ParameterType.Integer, 'User age', false)
+      ];
+
+      const params = {
+        name: 'John Doe'
+        // age is optional and missing
+      };
+
+      expect(() => {
+        ParameterValidator.validate(params, paramDefs, '/test-endpoint');
+      }).not.toThrow();
+    });
+
+    it('should distinguish between integer and number types', () => {
+      const paramDefs = [
+        new Parameter('count', ParameterType.Integer, 'Item count', true),
+        new Parameter('score', ParameterType.Number, 'Score value', true)
+      ];
+
+      const params1 = {
+        count: 25.5, // should be integer, not float
+        score: 85.5  // number is fine
+      };
+
+      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
+      };
+
+      expect(() => {
+        ParameterValidator.validate(params2, paramDefs, '/test-endpoint');
+      }).not.toThrow();
+    });
+
+    it('should handle array vs object distinction', () => {
+      const paramDefs = [
+        new Parameter('tags', ParameterType.List, 'Tags', true),
+        new Parameter('config', ParameterType.Dictionary, 'Config', true)
+      ];
+
+      const params = {
+        tags: { key: 'value' }, // should be array, not object
+        config: ['item1', 'item2'] // should be object, not array
+      };
+
+      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('nickname', ParameterType.String, 'Nickname', false)
+      ];
+
+      const params = {
+        name: 'John Doe',
+        nickname: null // optional param can be null
+      };
+
+      expect(() => {
+        ParameterValidator.validate(params, paramDefs, '/test-endpoint');
+      }).not.toThrow();
+    });
+
+    it('should handle edge cases for number validation', () => {
+      const paramDefs = [
+        new Parameter('value', ParameterType.Number, 'Number value', true)
+      ];
+
+      // 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, 'Count', true)
+      ];
+
+      // 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, 'Tags', true),
+        new Parameter('config', ParameterType.Dictionary, 'Config', true)
+      ];
+
+      const params = {
+        tags: [],
+        config: {}
+      };
+
+      expect(() => {
+        ParameterValidator.validate(params, paramDefs, '/test-endpoint');
+      }).not.toThrow();
+    });
+
+    it('should handle special string values', () => {
+      const paramDefs = [
+        new Parameter('value', ParameterType.String, 'String value', true)
+      ];
+
+      // 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 collect multiple validation errors', () => {
+      const paramDefs = [
+        new Parameter('name', ParameterType.String, 'Name', true),
+        new Parameter('age', ParameterType.Integer, 'Age', true),
+        new Parameter('email', ParameterType.String, 'Email', true)
+      ];
+
+      const params = {
+        // name is missing
+        age: 'invalid' // wrong type
+        // email is missing
+      };
+
+      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', () => {
+      expect(() => {
+        ParameterValidator.validate({ anyParam: 'value' }, [], '/test-endpoint');
+      }).not.toThrow();
+    });
+
+    it('should handle extra parameters not in definition', () => {
+      const paramDefs = [
+        new Parameter('name', ParameterType.String, 'Name', true)
+      ];
+
+      const params = {
+        name: 'John',
+        extraParam: 'ignored', // not in definition
+        anotherExtra: 123
+      };
+
+      // 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', true),
+        new Parameter('items', ParameterType.List, 'Items', true)
+      ];
+
+      const params = {
+        config: {
+          nested: {
+            deeply: {
+              nested: 'value'
+            }
+          }
+        },
+        items: [1, 2, [3, 4, [5, 6]]]
+      };
+
+      expect(() => {
+        ParameterValidator.validate(params, paramDefs, '/test-endpoint');
+      }).not.toThrow();
+    });
+  });
+});

package/src/validation/ParameterValidator.ts

@@ -0,0 +1,150 @@
+import { Parameter, ParameterType } from '../types/Models';
+import { ToolError, ValidationError } from '../types/ToolError';
+
+/**
+ * Parameter validator for tool inputs
+ */
+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
+   * @param _endpoint The endpoint being validated (reserved for future use)
+   * @throws {ToolError} When validation fails
+   */
+  public static validate(
+    params: any,
+    parameterDefinitions: Parameter[],
+    _endpoint: string
+  ): void {
+    const errors: ValidationError[] = [];
+
+    // Validate each defined parameter
+    for (const paramDef of parameterDefinitions) {
+      const value = params ? params[paramDef.name] : undefined;
+
+      // Check if required parameter is missing
+      if (paramDef.required && (value === undefined || value === null)) {
+        errors.push({
+          field: paramDef.name,
+          message: `Required parameter '${paramDef.name}' is missing`
+        });
+        continue;
+      }
+
+      // Skip validation if parameter is optional and not provided
+      if (!paramDef.required && (value === undefined || value === null)) {
+        continue;
+      }
+
+      // Validate parameter type
+      const typeError = this.validateParameterType(paramDef.name, value, paramDef.type);
+      if (typeError) {
+        errors.push(typeError);
+      }
+    }
+
+    // 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
+      );
+    }
+  }
+
+  /**
+   * Validate a single parameter's type
+   * @param paramName Parameter name
+   * @param value Parameter value
+   * @param expectedType Expected parameter type
+   * @returns Validation error if invalid, null if valid
+   */
+  private static validateParameterType(
+    paramName: string,
+    value: any,
+    expectedType: ParameterType
+  ): ValidationError | null {
+    const actualType = this.getActualType(value);
+
+    switch (expectedType) {
+    case ParameterType.String:
+      if (typeof value !== 'string') {
+        return {
+          field: paramName,
+          message: `Parameter '${paramName}' must be a string, but received ${actualType}`
+        };
+      }
+      break;
+
+    case ParameterType.Integer:
+      if (!Number.isInteger(value)) {
+        return {
+          field: paramName,
+          message: `Parameter '${paramName}' must be an integer, but received ${actualType}`
+        };
+      }
+      break;
+
+    case ParameterType.Number:
+      if (typeof value !== 'number' || isNaN(value)) {
+        return {
+          field: paramName,
+          message: `Parameter '${paramName}' must be a number, but received ${actualType}`
+        };
+      }
+      break;
+
+    case ParameterType.Boolean:
+      if (typeof value !== 'boolean') {
+        return {
+          field: paramName,
+          message: `Parameter '${paramName}' must be a boolean, but received ${actualType}`
+        };
+      }
+      break;
+
+    case ParameterType.List:
+      if (!Array.isArray(value)) {
+        return {
+          field: paramName,
+          message: `Parameter '${paramName}' must be an array, but received ${actualType}`
+        };
+      }
+      break;
+
+    case ParameterType.Dictionary:
+      if (typeof value !== 'object' || Array.isArray(value) || value === null) {
+        return {
+          field: paramName,
+          message: `Parameter '${paramName}' must be an object, but received ${actualType}`
+        };
+      }
+      break;
+
+    default:
+      return {
+        field: paramName,
+        message: `Parameter '${paramName}' has unknown expected type: ${String(expectedType)}`
+      };
+    }
+
+    return null;
+  }
+
+  /**
+   * Get a human-readable description of the actual type
+   * @param value The value to check
+   * @returns String description of the type
+   */
+  private static getActualType(value: any): string {
+    if (value === null) return 'null';
+    if (value === undefined) return 'undefined';
+    if (Array.isArray(value)) return 'array';
+    return typeof value;
+  }
+}