@optimizely-opal/opal-tool-ocp-sdk 1.0.0-beta.3 → 1.0.0-beta.5

package/src/service/Service.ts

@@ -1,5 +1,6 @@
 /* eslint-disable max-classes-per-file */
-import { AuthRequirement, Parameter } from '../types/Models';
+import { AuthRequirement, IslandResponse, Parameter } from '../types/Models';
+import { ToolError } from '../types/ToolError';
 import * as App from '@zaiusinc/app-sdk';
 import { logger, Headers } from '@zaiusinc/app-sdk';
 import { ToolFunction } from '../function/ToolFunction';
@@ -11,13 +12,20 @@ import { ParameterValidator } from '../validation/ParameterValidator';
  */
 const DEFAULT_OPTIID_AUTH = new AuthRequirement('OptiID', 'default', true);
 
+export class NestedInteractions {
+  public constructor(public response: IslandResponse) {
+  }
+}
+
 /**
  * Result type for interaction handlers
  */
 export class InteractionResult {
   public constructor(
     public message: string,
-    public link?: string
+    public link?: string,
+    public dispatch_event?: boolean,
+    public interactions?: NestedInteractions
   ) {}
 }
 
@@ -104,6 +112,37 @@ export class ToolsService {
     return [...(authRequirements || []), DEFAULT_OPTIID_AUTH];
   }
 
+  /**
+   * Format an error as RFC 9457 Problem Details response
+   * @param error The error to format
+   * @param instance URI reference identifying the specific occurrence
+   * @returns RFC 9457 compliant Response
+   */
+  private formatErrorResponse(error: any, instance: string): App.Response {
+    let status = 500;
+    let problemDetails: Record<string, unknown>;
+
+    if (error instanceof ToolError) {
+      // Use ToolError's status and format
+      status = error.status;
+      problemDetails = error.toProblemDetails(instance);
+    } else {
+      // Convert regular errors to RFC 9457 format with 500 status
+      problemDetails = {
+        title: 'Internal Server Error',
+        status: 500,
+        detail: error.message || 'An unexpected error occurred',
+        instance
+      };
+    }
+
+    return new App.Response(
+      status,
+      problemDetails,
+      new Headers([['content-type', 'application/problem+json']])
+    );
+  }
+
   /**
    * Register a tool function with generic auth data
    * @param name Tool name
@@ -175,20 +214,9 @@ export class ToolsService {
           }
 
           // Validate parameters before calling the handler (only if tool has parameter definitions)
+          // ParameterValidator.validate() throws ToolError if validation fails
           if (func.parameters && func.parameters.length > 0) {
-            const validationResult = ParameterValidator.validate(params, func.parameters);
-            if (!validationResult.isValid) {
-              return new App.Response(400, {
-                title: 'One or more validation errors occurred.',
-                status: 400,
-                detail: "See 'errors' field for details.",
-                instance: func.endpoint,
-                errors: validationResult.errors.map((error) => ({
-                  field: error.field,
-                  message: error.message
-                }))
-              }, new Headers([['content-type', 'application/problem+json']]));
-            }
+            ParameterValidator.validate(params, func.parameters, func.endpoint);
           }
 
           // Extract auth data from body JSON
@@ -198,7 +226,7 @@ export class ToolsService {
           return new App.Response(200, result);
         } catch (error: any) {
           logger.error(`Error in function ${func.name}:`, error);
-          return new App.Response(500, { error: error.message || 'Unknown error' });
+          return this.formatErrorResponse(error, func.endpoint);
         }
       }
 
@@ -219,7 +247,7 @@ export class ToolsService {
           return new App.Response(200, result);
         } catch (error: any) {
           logger.error(`Error in function ${interaction.name}:`, error);
-          return new App.Response(500, { error: error.message || 'Unknown error' });
+          return this.formatErrorResponse(error, interaction.endpoint);
         }
       }
 

package/src/types/ToolError.test.ts

@@ -0,0 +1,222 @@
+import { ToolError } from './ToolError';
+
+describe('ToolError', () => {
+  describe('constructor', () => {
+    it('should create error with message and default status 500', () => {
+      const error = new ToolError('Something went wrong');
+
+      expect(error.message).toBe('[500] Something went wrong');
+      expect(error.title).toBe('Something went wrong');
+      expect(error.status).toBe(500);
+      expect(error.detail).toBeUndefined();
+      expect(error.name).toBe('ToolError');
+    });
+
+    it('should create error with custom status code', () => {
+      const error = new ToolError('Not found', 404);
+
+      expect(error.message).toBe('[404] Not found');
+      expect(error.title).toBe('Not found');
+      expect(error.status).toBe(404);
+      expect(error.detail).toBeUndefined();
+    });
+
+    it('should create error with message, status, and detail', () => {
+      const error = new ToolError('Validation failed', 400, 'Email format is invalid');
+
+      expect(error.message).toBe('[400] Validation failed: Email format is invalid');
+      expect(error.title).toBe('Validation failed');
+      expect(error.status).toBe(400);
+      expect(error.detail).toBe('Email format is invalid');
+    });
+
+    it('should create error with errors array in message', () => {
+      const errors = [
+        { field: 'email', message: 'Invalid email format' },
+        { field: 'age', message: 'Must be a positive number' }
+      ];
+      const error = new ToolError('Validation failed', 400, "See 'errors' field for details.", errors);
+
+      expect(error.message).toBe(
+        '[400] Validation failed: email (Invalid email format); age (Must be a positive number)'
+      );
+      expect(error.title).toBe('Validation failed');
+      expect(error.status).toBe(400);
+      expect(error.detail).toBe("See 'errors' field for details.");
+      expect(error.errors).toEqual(errors);
+    });
+
+    it('should create error with single error in message', () => {
+      const errors = [{ field: 'username', message: 'Required field is missing' }];
+      const error = new ToolError('Validation failed', 400, undefined, errors);
+
+      expect(error.message).toBe('[400] Validation failed: username (Required field is missing)');
+      expect(error.title).toBe('Validation failed');
+      expect(error.status).toBe(400);
+      expect(error.detail).toBeUndefined();
+      expect(error.errors).toEqual(errors);
+    });
+
+    it('should be an instance of Error', () => {
+      const error = new ToolError('Test error');
+
+      expect(error).toBeInstanceOf(Error);
+      expect(error).toBeInstanceOf(ToolError);
+    });
+
+    it('should have a stack trace', () => {
+      const error = new ToolError('Test error');
+
+      expect(error.stack).toBeDefined();
+      expect(error.stack).toContain('ToolError');
+    });
+  });
+
+  describe('toProblemDetails', () => {
+    it('should convert to RFC 9457 format with all fields', () => {
+      const error = new ToolError('Resource not found', 404, 'The task with ID 123 does not exist');
+      const problemDetails = error.toProblemDetails('/api/tasks/123');
+
+      expect(problemDetails).toEqual({
+        title: 'Resource not found',
+        status: 404,
+        detail: 'The task with ID 123 does not exist',
+        instance: '/api/tasks/123'
+      });
+    });
+
+    it('should omit detail field when not provided', () => {
+      const error = new ToolError('Bad request', 400);
+      const problemDetails = error.toProblemDetails('/api/tasks');
+
+      expect(problemDetails).toEqual({
+        title: 'Bad request',
+        status: 400,
+        instance: '/api/tasks'
+      });
+      expect(problemDetails).not.toHaveProperty('detail');
+    });
+
+    it('should include default status 500', () => {
+      const error = new ToolError('Internal error');
+      const problemDetails = error.toProblemDetails('/api/endpoint');
+
+      expect(problemDetails).toEqual({
+        title: 'Internal error',
+        status: 500,
+        instance: '/api/endpoint'
+      });
+    });
+
+    it('should handle different instance paths', () => {
+      const error = new ToolError('Error', 500, 'Details');
+      const problemDetails1 = error.toProblemDetails('/api/v1/resource');
+      const problemDetails2 = error.toProblemDetails('/webhook/callback');
+
+      expect(problemDetails1.instance).toBe('/api/v1/resource');
+      expect(problemDetails2.instance).toBe('/webhook/callback');
+    });
+
+    it('should include errors array when provided', () => {
+      const errors = [
+        { field: 'email', message: 'Invalid email format' },
+        { field: 'age', message: 'Must be a positive number' }
+      ];
+      const error = new ToolError('Validation failed', 400, "See 'errors' field for details.", errors);
+      const problemDetails = error.toProblemDetails('/api/users');
+
+      expect(problemDetails).toEqual({
+        title: 'Validation failed',
+        status: 400,
+        detail: "See 'errors' field for details.",
+        instance: '/api/users',
+        errors: [
+          { field: 'email', message: 'Invalid email format' },
+          { field: 'age', message: 'Must be a positive number' }
+        ]
+      });
+    });
+
+    it('should omit errors field when empty array', () => {
+      const error = new ToolError('Error', 400, 'Detail', []);
+      const problemDetails = error.toProblemDetails('/api/endpoint');
+
+      expect(problemDetails).toEqual({
+        title: 'Error',
+        status: 400,
+        detail: 'Detail',
+        instance: '/api/endpoint'
+      });
+      expect(problemDetails).not.toHaveProperty('errors');
+    });
+
+    it('should omit errors field when not provided', () => {
+      const error = new ToolError('Error', 400, 'Detail');
+      const problemDetails = error.toProblemDetails('/api/endpoint');
+
+      expect(problemDetails).toEqual({
+        title: 'Error',
+        status: 400,
+        detail: 'Detail',
+        instance: '/api/endpoint'
+      });
+      expect(problemDetails).not.toHaveProperty('errors');
+    });
+
+    it('should support errors without detail field', () => {
+      const errors = [{ field: 'name', message: 'Required' }];
+      const error = new ToolError('Validation failed', 400, undefined, errors);
+      const problemDetails = error.toProblemDetails('/api/endpoint');
+
+      expect(problemDetails).toEqual({
+        title: 'Validation failed',
+        status: 400,
+        instance: '/api/endpoint',
+        errors: [{ field: 'name', message: 'Required' }]
+      });
+      expect(problemDetails).not.toHaveProperty('detail');
+    });
+  });
+
+  describe('common HTTP status codes', () => {
+    it('should support 400 Bad Request', () => {
+      const error = new ToolError('Bad Request', 400);
+      expect(error.status).toBe(400);
+    });
+
+    it('should support 401 Unauthorized', () => {
+      const error = new ToolError('Unauthorized', 401);
+      expect(error.status).toBe(401);
+    });
+
+    it('should support 403 Forbidden', () => {
+      const error = new ToolError('Forbidden', 403);
+      expect(error.status).toBe(403);
+    });
+
+    it('should support 404 Not Found', () => {
+      const error = new ToolError('Not Found', 404);
+      expect(error.status).toBe(404);
+    });
+
+    it('should support 409 Conflict', () => {
+      const error = new ToolError('Conflict', 409);
+      expect(error.status).toBe(409);
+    });
+
+    it('should support 422 Unprocessable Entity', () => {
+      const error = new ToolError('Unprocessable Entity', 422);
+      expect(error.status).toBe(422);
+    });
+
+    it('should support 500 Internal Server Error', () => {
+      const error = new ToolError('Internal Server Error', 500);
+      expect(error.status).toBe(500);
+    });
+
+    it('should support 503 Service Unavailable', () => {
+      const error = new ToolError('Service Unavailable', 503);
+      expect(error.status).toBe(503);
+    });
+  });
+});

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;
+  }
+}