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

package/src/logging/ToolLogger.ts

@@ -1,6 +1,10 @@
 import { logger, LogVisibility } from '@zaiusinc/app-sdk';
 import * as App from '@zaiusinc/app-sdk';
 
+const MAX_PARAM_LOG_LENGTH = 128;
+const MAX_BODY_LOG_LENGTH = 256;
+const MAX_ARRAY_ITEMS = 2;
+
 /**
  * Utility class for logging Opal tool requests and responses with security considerations
  */
@@ -48,13 +52,13 @@ export class ToolLogger {
     '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 {
+  private static redactSensitiveDataAndTruncate(data: any, maxDepth = 5, accumulatedLength = 0): any {
+    if (accumulatedLength > MAX_BODY_LOG_LENGTH) {
+      return '';
+    }
     if (maxDepth <= 0) {
       return '[MAX_DEPTH_EXCEEDED]';
     }
@@ -64,9 +68,13 @@ export class ToolLogger {
     }
 
     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 (data.length > MAX_PARAM_LOG_LENGTH) {
+        const lead = data.substring(0, MAX_PARAM_LOG_LENGTH - 10);
+        const tail = data.substring(data.length - 10);
+        return `${lead}...[${data.length - MAX_PARAM_LOG_LENGTH} truncated]...${tail}`;
+      } else {
+        return data;
+      }
     }
 
     if (typeof data === 'number' || typeof data === 'boolean') {
@@ -74,10 +82,10 @@ export class ToolLogger {
     }
 
     if (Array.isArray(data)) {
-      const truncated = data.slice(0, this.MAX_ARRAY_ITEMS);
-      const result = truncated.map((item) => this.redactSensitiveData(item, maxDepth));
-      if (data.length > this.MAX_ARRAY_ITEMS) {
-        result.push(`... (${data.length - this.MAX_ARRAY_ITEMS} more items truncated)`);
+      const truncated = data.slice(0, MAX_ARRAY_ITEMS);
+      const result = truncated.map((item) => this.redactSensitiveDataAndTruncate(item, maxDepth, accumulatedLength));
+      if (data.length > MAX_ARRAY_ITEMS) {
+        result.push(`... (${data.length - MAX_ARRAY_ITEMS} more items truncated)`);
       }
       return result;
     }
@@ -85,13 +93,20 @@ export class ToolLogger {
     if (typeof data === 'object') {
       const result: any = {};
       for (const [key, value] of Object.entries(data)) {
+        if (accumulatedLength > MAX_BODY_LOG_LENGTH) {
+          break;
+        }
         // 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);
+          result[key] = this.redactSensitiveDataAndTruncate(value, maxDepth - 1, accumulatedLength);
+        }
+
+        if (result[key]) {
+          accumulatedLength += JSON.stringify(result[key]).length;
         }
       }
       return result;
@@ -118,7 +133,7 @@ export class ToolLogger {
       return null;
     }
 
-    return this.redactSensitiveData(params);
+    return this.redactSensitiveDataAndTruncate(params);
   }
 
   /**
@@ -136,6 +151,99 @@ export class ToolLogger {
     }
   }
 
+  /**
+   * Extracts the response body as a string or parsed JSON object
+   */
+  private static getResponseBody(response?: App.Response): any {
+    if (!response) {
+      return null;
+    }
+
+    try {
+      const contentType = response.headers?.get('content-type') || '';
+      const isJson = contentType.includes('application/json') || contentType.includes('application/problem+json');
+      const isText = contentType.startsWith('text/');
+
+      if (!isJson && !isText) {
+        return null;
+      }
+
+      // Try to access bodyAsU8Array - this may throw
+      const bodyData = response.bodyAsU8Array;
+      if (!bodyData) {
+        return null;
+      }
+
+      // Convert Uint8Array to string
+      const bodyString = Buffer.from(bodyData).toString();
+      if (!bodyString) {
+        return null;
+      }
+
+      // Try to parse as JSON if content-type indicates JSON
+      if (isJson) {
+        try {
+          return JSON.parse(bodyString);
+        } catch {
+          // If JSON parsing fails, return as string
+          return bodyString;
+        }
+      }
+
+      // Return as plain text for non-JSON content types
+      return bodyString;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Creates a summary of response body with security redaction and truncation
+   * For failed responses (4xx, 5xx): returns full body with redacted sensitive data
+   * For successful responses (2xx): returns first 100 chars with redacted sensitive data
+   */
+  private static createResponseBodySummary(response?: App.Response, success?: boolean): any {
+    const body = this.getResponseBody(response);
+    if (body === null || body === undefined) {
+      return null;
+    }
+
+    // For objects (parsed JSON), apply redaction
+    if (typeof body === 'object') {
+      // For failed responses, don't truncate strings within the object
+      const redactedBody = this.redactSensitiveDataAndTruncate(body, 5);
+
+      // For successful responses, truncate to first MAX_BODY_LOG_LENGTH chars
+      if (success) {
+        const bodyString = JSON.stringify(redactedBody);
+        if (bodyString.length > MAX_BODY_LOG_LENGTH) {
+          const truncated = bodyString.substring(0, MAX_BODY_LOG_LENGTH);
+          return `${truncated}... (truncated)`;
+        }
+        return redactedBody;
+      }
+
+      // For failed responses, return full redacted body
+      return redactedBody;
+    }
+
+    // For strings (plain text or unparseable JSON)
+    if (typeof body === 'string') {
+      // For successful responses, truncate to first 100 chars
+      if (success) {
+        if (body.length > MAX_BODY_LOG_LENGTH) {
+          return `${body.substring(0, MAX_BODY_LOG_LENGTH)}... (truncated)`;
+        }
+        return body;
+      }
+
+      // For failed responses, return full body
+      return body;
+    }
+
+    return body;
+  }
+
   /**
    * Logs an incoming request
    */
@@ -162,16 +270,22 @@ export class ToolLogger {
     response: App.Response,
     processingTimeMs?: number
   ): void {
-    const responseLog = {
+    const success = response.status >= 200 && response.status < 300;
+    const responseLog: any = {
       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
+      success
     };
 
+    const responseBodySummary = this.createResponseBodySummary(response, success);
+    if (responseBodySummary) {
+      responseLog.responseBody = responseBodySummary;
+    }
+
     // Log with Zaius audience so developers only see requests for accounts they have access to
     logger.info(LogVisibility.Zaius, JSON.stringify(responseLog));
   }

package/src/types/Models.ts

@@ -143,7 +143,9 @@ export class IslandConfig {
 
   public constructor(
     public fields: IslandField[],
-    public actions: IslandAction[]
+    public actions: IslandAction[],
+    public type?: 'card' | 'button',
+    public icon?: string,
   ) {}
 }
 
@@ -161,3 +163,8 @@ export class IslandResponse {
   }
 }
 
+export interface ReadyResponse {
+  ready: boolean;
+  reason?: string;
+}
+

package/src/types/ToolError.test.ts

@@ -5,7 +5,8 @@ describe('ToolError', () => {
     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.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');
@@ -14,7 +15,8 @@ describe('ToolError', () => {
     it('should create error with custom status code', () => {
       const error = new ToolError('Not found', 404);
 
-      expect(error.message).toBe('Not found');
+      expect(error.message).toBe('[404] Not found');
+      expect(error.title).toBe('Not found');
       expect(error.status).toBe(404);
       expect(error.detail).toBeUndefined();
     });
@@ -22,11 +24,39 @@ describe('ToolError', () => {
     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.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');
 

package/src/types/ToolError.ts

@@ -9,18 +9,27 @@ export interface ValidationError {
 /**
  * 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' }
@@ -43,6 +52,11 @@ export class ToolError extends Error {
    */
   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
    *
@@ -57,8 +71,24 @@ export class ToolError extends Error {
     detail?: string,
     errors?: ValidationError[]
   ) {
-    super(message);
+    // 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;
@@ -77,7 +107,7 @@ export class ToolError extends Error {
    */
   public toProblemDetails(instance: string): Record<string, unknown> {
     const problemDetails: Record<string, unknown> = {
-      title: this.message,
+      title: this.title,
       status: this.status,
       instance
     };

package/src/validation/ParameterValidator.test.ts

@@ -49,7 +49,10 @@ describe('ParameterValidator', () => {
         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.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([{