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

package/src/logging/ToolLogger.ts

@@ -0,0 +1,177 @@
+import { logger, LogVisibility } from '@zaiusinc/app-sdk';
+import * as App from '@zaiusinc/app-sdk';
+
+/**
+ * Utility class for logging Opal tool requests and responses with security considerations
+ */
+export class ToolLogger {
+  private static readonly SENSITIVE_FIELDS = [
+    // Authentication / secrets
+    'password',
+    'pass',
+    'secret',
+    'key',
+    'token',
+    'auth',
+    'credentials',
+    'access_token',
+    'refresh_token',
+    'api_key',
+    'private_key',
+    'client_secret',
+    'session_token',
+    'authorization',
+
+    // Payment-related
+    'card_number',
+    'credit_card',
+    'cvv',
+    'expiry_date',
+
+    // Personal info
+    'ssn', // social security number
+    'nid', // national ID
+    'passport',
+    'dob', // date of birth
+    'email',
+    'phone',
+    'address',
+
+    // Misc / environment
+    'otp',
+    'pin',
+    'security_answer',
+    'security_question',
+    'signing_key',
+    'encryption_key',
+    'jwt',
+    'bearer_token'
+  ];
+
+  private static readonly MAX_PARAM_LENGTH = 100;
+  private static readonly MAX_ARRAY_ITEMS = 10;
+
+  /**
+   * Redacts sensitive data from an object
+   */
+  private static redactSensitiveData(data: any, maxDepth = 5): any {
+    if (maxDepth <= 0) {
+      return '[MAX_DEPTH_EXCEEDED]';
+    }
+
+    if (data === null || data === undefined) {
+      return data;
+    }
+
+    if (typeof data === 'string') {
+      return data.length > this.MAX_PARAM_LENGTH
+        ? `${data.substring(0, this.MAX_PARAM_LENGTH)}... (truncated, ${data.length} chars total)`
+        : data;
+    }
+
+    if (typeof data === 'number' || typeof data === 'boolean') {
+      return data;
+    }
+
+    if (Array.isArray(data)) {
+      const truncated = data.slice(0, this.MAX_ARRAY_ITEMS);
+      const result = truncated.map((item) => this.redactSensitiveData(item, maxDepth - 1));
+      if (data.length > this.MAX_ARRAY_ITEMS) {
+        result.push(`... (${data.length - this.MAX_ARRAY_ITEMS} more items truncated)`);
+      }
+      return result;
+    }
+
+    if (typeof data === 'object') {
+      const result: any = {};
+      for (const [key, value] of Object.entries(data)) {
+        // Check if this field contains sensitive data
+        const isSensitive = this.isSensitiveField(key);
+
+        if (isSensitive) {
+          result[key] = '[REDACTED]';
+        } else {
+          result[key] = this.redactSensitiveData(value, maxDepth - 1);
+        }
+      }
+      return result;
+    }
+
+    return data;
+  }
+
+  /**
+   * Checks if a field name is considered sensitive
+   */
+  private static isSensitiveField(fieldName: string): boolean {
+    const lowerKey = fieldName.toLowerCase();
+    return this.SENSITIVE_FIELDS.some((sensitiveField) =>
+      lowerKey.includes(sensitiveField)
+    );
+  }
+
+  /**
+   * Creates a summary of request parameters
+   */
+  private static createParameterSummary(params: any): any {
+    if (!params) {
+      return null;
+    }
+
+    return this.redactSensitiveData(params);
+  }
+
+  /**
+   * Calculates content length of response data
+   */
+  private static calculateContentLength(response?: App.Response) {
+    if (!response) {
+      return 0;
+    }
+
+    try {
+      return response.bodyAsU8Array?.length || 'unknown';
+    } catch {
+      return 'unknown';
+    }
+  }
+
+  /**
+   * Logs an incoming request
+   */
+  public static logRequest(
+    req: App.Request,
+  ): void {
+    const params = req.bodyJSON && req.bodyJSON.parameters ? req.bodyJSON.parameters : req.bodyJSON;
+    const requestLog = {
+      event: 'opal_tool_request',
+      path: req.path,
+      parameters: this.createParameterSummary(params)
+    };
+
+    // Log with Zaius audience so developers only see requests for accounts they have access to
+    logger.info(LogVisibility.Zaius, JSON.stringify(requestLog));
+  }
+
+  /**
+   * Logs a successful response
+   */
+  public static logResponse(
+    req: App.Request,
+    response: App.Response,
+    processingTimeMs?: number
+  ): void {
+    const responseLog = {
+      event: 'opal_tool_response',
+      path: req.path,
+      duration: processingTimeMs ? `${processingTimeMs}ms` : undefined,
+      status: response.status,
+      contentType: response.headers?.get('content-type') || 'unknown',
+      contentLength: this.calculateContentLength(response),
+      success: response.status >= 200 && response.status < 300
+    };
+
+    // Log with Zaius audience so developers only see requests for accounts they have access to
+    logger.info(LogVisibility.Zaius, JSON.stringify(responseLog));
+  }
+}

package/src/service/Service.test.ts

@@ -1,5 +1,6 @@
 import { toolsService, Tool, Interaction } from './Service';
 import { Parameter, ParameterType, AuthRequirement, OptiIdAuthDataCredentials, OptiIdAuthData } from '../types/Models';
+import { ToolError } from '../types/ToolError';
 import { ToolFunction } from '../function/ToolFunction';
 import { logger } from '@zaiusinc/app-sdk';
 
@@ -370,7 +371,7 @@ describe('ToolsService', () => {
         );
       });
 
-      it('should return 500 error when tool handler throws an error', async () => {
+      it('should return 500 error in RFC 9457 format when tool handler throws a regular error', async () => {
         const errorMessage = 'Tool execution failed';
         jest.mocked(mockTool.handler).mockRejectedValueOnce(new Error(errorMessage));
 
@@ -378,6 +379,13 @@ describe('ToolsService', () => {
         const response = await toolsService.processRequest(mockRequest, mockToolFunction);
 
         expect(response.status).toBe(500);
+        expect(response.bodyJSON).toEqual({
+          title: 'Internal Server Error',
+          status: 500,
+          detail: errorMessage,
+          instance: mockTool.endpoint
+        });
+        expect(response.headers.get('content-type')).toBe('application/problem+json');
         expect(logger.error).toHaveBeenCalledWith(
           `Error in function ${mockTool.name}:`,
           expect.any(Error)
@@ -391,6 +399,67 @@ describe('ToolsService', () => {
         const response = await toolsService.processRequest(mockRequest, mockToolFunction);
 
         expect(response.status).toBe(500);
+        expect(response.bodyJSON).toEqual({
+          title: 'Internal Server Error',
+          status: 500,
+          detail: 'An unexpected error occurred',
+          instance: mockTool.endpoint
+        });
+        expect(response.headers.get('content-type')).toBe('application/problem+json');
+      });
+
+      it('should return custom status code when tool handler throws ToolError', async () => {
+        const toolError = new ToolError('Resource not found', 404, 'The requested task does not exist');
+        jest.mocked(mockTool.handler).mockRejectedValueOnce(toolError);
+
+        const mockRequest = createMockRequest();
+        const response = await toolsService.processRequest(mockRequest, mockToolFunction);
+
+        expect(response.status).toBe(404);
+        expect(response.bodyJSON).toEqual({
+          title: 'Resource not found',
+          status: 404,
+          detail: 'The requested task does not exist',
+          instance: mockTool.endpoint
+        });
+        expect(response.headers.get('content-type')).toBe('application/problem+json');
+        expect(logger.error).toHaveBeenCalledWith(
+          `Error in function ${mockTool.name}:`,
+          expect.any(ToolError)
+        );
+      });
+
+      it('should return ToolError without detail field when detail is not provided', async () => {
+        const toolError = new ToolError('Bad request', 400);
+        jest.mocked(mockTool.handler).mockRejectedValueOnce(toolError);
+
+        const mockRequest = createMockRequest();
+        const response = await toolsService.processRequest(mockRequest, mockToolFunction);
+
+        expect(response.status).toBe(400);
+        expect(response.bodyJSON).toEqual({
+          title: 'Bad request',
+          status: 400,
+          instance: mockTool.endpoint
+        });
+        expect(response.bodyJSON).not.toHaveProperty('detail');
+        expect(response.headers.get('content-type')).toBe('application/problem+json');
+      });
+
+      it('should default to 500 when ToolError is created without status', async () => {
+        const toolError = new ToolError('Database error');
+        jest.mocked(mockTool.handler).mockRejectedValueOnce(toolError);
+
+        const mockRequest = createMockRequest();
+        const response = await toolsService.processRequest(mockRequest, mockToolFunction);
+
+        expect(response.status).toBe(500);
+        expect(response.bodyJSON).toEqual({
+          title: 'Database error',
+          status: 500,
+          instance: mockTool.endpoint
+        });
+        expect(response.headers.get('content-type')).toBe('application/problem+json');
       });
     });
 
@@ -488,7 +557,7 @@ describe('ToolsService', () => {
         );
       });
 
-      it('should return 500 error when interaction handler throws an error', async () => {
+      it('should return 500 error in RFC 9457 format when interaction handler throws a regular error', async () => {
         const errorMessage = 'Interaction execution failed';
         jest.mocked(mockInteraction.handler).mockRejectedValueOnce(new Error(errorMessage));
 
@@ -500,11 +569,43 @@ describe('ToolsService', () => {
         const response = await toolsService.processRequest(interactionRequest, mockToolFunction);
 
         expect(response.status).toBe(500);
+        expect(response.bodyJSON).toEqual({
+          title: 'Internal Server Error',
+          status: 500,
+          detail: errorMessage,
+          instance: mockInteraction.endpoint
+        });
+        expect(response.headers.get('content-type')).toBe('application/problem+json');
         expect(logger.error).toHaveBeenCalledWith(
           `Error in function ${mockInteraction.name}:`,
           expect.any(Error)
         );
       });
+
+      it('should return custom status code when interaction handler throws ToolError', async () => {
+        const toolError = new ToolError('Webhook validation failed', 400, 'Invalid signature');
+        jest.mocked(mockInteraction.handler).mockRejectedValueOnce(toolError);
+
+        const interactionRequest = createMockRequest({
+          path: '/test-interaction',
+          bodyJSON: { data: { param1: 'test-value' } }
+        });
+
+        const response = await toolsService.processRequest(interactionRequest, mockToolFunction);
+
+        expect(response.status).toBe(400);
+        expect(response.bodyJSON).toEqual({
+          title: 'Webhook validation failed',
+          status: 400,
+          detail: 'Invalid signature',
+          instance: mockInteraction.endpoint
+        });
+        expect(response.headers.get('content-type')).toBe('application/problem+json');
+        expect(logger.error).toHaveBeenCalledWith(
+          `Error in function ${mockInteraction.name}:`,
+          expect.any(ToolError)
+        );
+      });
     });
 
     describe('error cases', () => {

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,192 @@
+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('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('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('Validation failed');
+      expect(error.status).toBe(400);
+      expect(error.detail).toBe('Email format is invalid');
+    });
+
+    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);
+    });
+  });
+});