@optimizely-opal/opal-tool-ocp-sdk 1.0.0-beta.7 → 1.0.0-beta.9

package/src/service/Service.ts

@@ -2,7 +2,7 @@
 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 { logger, Headers, getAppContext } from '@zaiusinc/app-sdk';
 import { ToolFunction } from '../function/ToolFunction';
 import { GlobalToolFunction } from '../function/GlobalToolFunction';
 import { ParameterValidator } from '../validation/ParameterValidator';
@@ -17,6 +17,27 @@ export class NestedInteractions {
   }
 }
 
+/**
+ * Interface for tool description override data (compatible with KV store)
+ */
+interface ToolOverride extends App.ValueHash {
+  name: string;
+  description: string;
+  parameters: ParameterOverride[];
+}
+
+interface ParameterOverride extends App.ValueHash {
+  name: string;
+  description: string;
+}
+
+/**
+ * Interface for stored override data in KV store
+ */
+interface StoredOverrides extends App.ValueHash {
+  [tool_name: string]: ToolOverride;
+}
+
 /**
  * Result type for interaction handlers
  */
@@ -96,6 +117,107 @@ export class ToolsService {
   private functions: Map<string, Tool<any>> = new Map();
   private interactions: Map<string, Interaction<any>> = new Map();
 
+  /**
+   * Generate KV store key for tool overrides
+   * @param appVersionId App version ID
+   * @param functionName Function name
+   * @returns KV store key
+   */
+  private getOverrideKey(appVersionId: string, functionName: string): string {
+    return `${appVersionId}:${functionName}:opal-tools-overrides`;
+  }
+
+  /**
+   * Get tool overrides from KV store
+   * @param appVersionId App version ID
+   * @param functionName Function name
+   * @returns Stored overrides or null if not found
+   */
+  private async getOverrides(appVersionId: string, functionName: string): Promise<StoredOverrides> {
+    const key = this.getOverrideKey(appVersionId, functionName);
+    return await App.storage.kvStore.get<StoredOverrides>(key);
+  }
+
+  /**
+   * Apply overrides to tool definitions
+   * @param tools Original tool definitions
+   * @param overrides Override data
+   * @returns Tools with overrides applied
+   */
+  private applyOverrides(tools: Array<Tool<any>>, overrides: StoredOverrides): Array<Tool<any>> {
+    return tools.map((tool) => {
+      const override = overrides[tool.name];
+      if (!override) {
+        return tool;
+      }
+
+      // Clone the tool and apply overrides
+      const overriddenTool = new Tool(
+        tool.name,
+        override.description,
+        tool.parameters.map((param) => {
+          const paramOverride = override.parameters?.find((p) => p.name === param.name);
+          if (paramOverride) {
+            return new Parameter(
+              param.name,
+              param.type,
+              paramOverride.description,
+              param.required
+            );
+          }
+          return param;
+        }),
+        tool.endpoint,
+        tool.handler,
+        tool.authRequirements
+      );
+      overriddenTool.httpMethod = tool.httpMethod;
+      return overriddenTool;
+    });
+  }
+
+  /**
+   * Save tool description overrides
+   * @param appVersionId App version ID
+   * @param functionName Function name
+   * @param overrideData Override data from request
+   */
+  public async saveToolOverrides(
+    appVersionId: string,
+    functionName: string,
+    overrides: StoredOverrides
+  ): Promise<void> {
+    const key = this.getOverrideKey(appVersionId, functionName);
+    await App.storage.kvStore.patch(key, overrides);
+  }
+
+  /**
+   * Delete tool description overrides
+   * @param appVersionId App version ID
+   * @param functionName Function name
+   */
+  public async deleteToolOverrides(appVersionId: string, functionName: string): Promise<void> {
+    const key = this.getOverrideKey(appVersionId, functionName);
+    await App.storage.kvStore.delete(key);
+  }
+
+  /**
+   * Get tool definitions with overrides applied
+   * @param appVersionId App version ID
+   * @param functionName Function name
+   * @returns Tool definitions with overrides applied
+   */
+  public async getToolsWithOverrides(appVersionId: string, functionName: string): Promise<Array<Tool<any>>> {
+    const tools = Array.from(this.functions.values());
+    const overrides = await this.getOverrides(appVersionId, functionName);
+
+    if (overrides) {
+      return this.applyOverrides(tools, overrides);
+    }
+
+    return tools;
+  }
+
   /**
    * Enforce OptiID authentication for tools by ensuring OptiID auth requirement is present
    * @param authRequirements Original authentication requirements
@@ -200,59 +322,141 @@ export class ToolsService {
     req: App.Request,
     functionContext: ToolFunction | GlobalToolFunction
   ): Promise<App.Response> {
+    // Handle discovery endpoint with overrides
     if (req.path === '/discovery') {
-      return new App.Response(200, { functions: Array.from(this.functions.values()).map((f) => f.toJSON()) });
-    } else {
-      const func = this.functions.get(req.path);
-      if (func) {
-        try {
-          let params;
-          if (req.bodyJSON && req.bodyJSON.parameters) {
-            params = req.bodyJSON.parameters;
-          } else {
-            params = req.bodyJSON;
-          }
+      return await this.handleDiscoveryRequest(functionContext);
+    }
 
-          // 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) {
-            ParameterValidator.validate(params, func.parameters, func.endpoint);
-          }
+    // Handle overrides endpoint
+    if (req.path === '/overrides') {
+      return await this.handleOverridesRequest(req, functionContext);
+    }
 
-          // Extract auth data from body JSON
-          const authData = req.bodyJSON ? req.bodyJSON.auth : undefined;
+    // Handle regular tool functions
+    const func = this.functions.get(req.path);
+    if (func) {
+      try {
+        let params;
+        if (req.bodyJSON && req.bodyJSON.parameters) {
+          params = req.bodyJSON.parameters;
+        } else {
+          params = req.bodyJSON;
+        }
 
-          const result = await func.handler(functionContext, params, authData);
-          return new App.Response(200, result);
-        } catch (error: any) {
-          logger.error(`Error in function ${func.name}:`, error);
-          return this.formatErrorResponse(error, func.endpoint);
+        // 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) {
+          ParameterValidator.validate(params, func.parameters, func.endpoint);
         }
+
+        // Extract auth data from body JSON
+        const authData = req.bodyJSON ? req.bodyJSON.auth : undefined;
+        const result = await func.handler(functionContext, params, authData);
+        return new App.Response(200, result);
+      } catch (error: any) {
+        logger.error(`Error in function ${func.name}:`, error);
+        return this.formatErrorResponse(error, func.endpoint);
       }
+    }
 
-      const interaction = this.interactions.get(req.path);
-      if (interaction) {
-        try {
-          let params;
-          if (req.bodyJSON && req.bodyJSON.data) {
-            params = req.bodyJSON.data;
-          } else {
-            params = req.bodyJSON;
-          }
+    // Handle interactions
+    const interaction = this.interactions.get(req.path);
+    if (interaction) {
+      try {
+        let params;
+        if (req.bodyJSON && req.bodyJSON.data) {
+          params = req.bodyJSON.data;
+        } else {
+          params = req.bodyJSON;
+        }
+
+        // Extract auth data from body JSON
+        const authData = req.bodyJSON ? req.bodyJSON.auth : undefined;
+
+        const result = await interaction.handler(functionContext, params, authData);
+        return new App.Response(200, result);
+      } catch (error: any) {
+        logger.error(`Error in function ${interaction.name}:`, error);
+        return this.formatErrorResponse(error, interaction.endpoint);
+
+      }
+    }
+    return new App.Response(404, 'Function not found');
+  }
+
+  /**
+   * Handle discovery endpoint with overrides applied
+   * @param functionContext The function context to get function name from
+   * @returns Response with tool definitions
+   */
+  private async handleDiscoveryRequest(functionContext: ToolFunction | GlobalToolFunction): Promise<App.Response> {
+    try {
+      // Get app version from app context
+      const appVersionId = getAppContext().manifest.meta.version;
+      // Get function name from function context
+      const functionName = functionContext.constructor.name;
+
+      const toolsWithOverrides = await this.getToolsWithOverrides(appVersionId, functionName);
+      return new App.Response(200, { functions: toolsWithOverrides.map((f) => f.toJSON()) });
+    } catch (error: any) {
+      logger.error('Error getting tools with overrides:', error);
+      // Fallback to original tools if override fetch fails
+      return new App.Response(200, { functions: Array.from(this.functions.values()).map((f) => f.toJSON()) });
+    }
+  }
 
-          // Extract auth data from body JSON
-          const authData = req.bodyJSON ? req.bodyJSON.auth : undefined;
+  /**
+   * Handle overrides endpoint for saving and deleting tool description overrides
+   * @param req The request object
+   * @param functionContext The function context to get function name from
+   * @returns Response indicating success or failure
+   */
+  private async handleOverridesRequest(
+    req: App.Request,
+    functionContext: ToolFunction | GlobalToolFunction
+  ): Promise<App.Response> {
+    if (req.method === 'PATCH') {
+      try {
+        // Get app version from app context
+        const appVersionId = getAppContext().manifest.meta.version;
+        // Get function name from function context
+        const functionName = functionContext.constructor.name;
 
-          const result = await interaction.handler(functionContext, params, authData);
-          return new App.Response(200, result);
-        } catch (error: any) {
-          logger.error(`Error in function ${interaction.name}:`, error);
-          return this.formatErrorResponse(error, interaction.endpoint);
+        if (!req.bodyJSON?.functions || !Array.isArray(req.bodyJSON.functions)) {
+          return new App.Response(400, { error: 'Invalid request body. Expected functions array.' });
         }
+
+        // Convert array format to map format for storage
+        const overrideData: StoredOverrides = (req.bodyJSON.functions as ToolOverride[]).reduce(
+          (map: StoredOverrides, tool: ToolOverride) => {
+            map[tool.name] = tool;
+            return map;
+          },
+          {}
+        );
+
+        await this.saveToolOverrides(appVersionId, functionName, overrideData);
+        return new App.Response(200, { success: true });
+      } catch (error: any) {
+        logger.error('Error saving tool overrides:', error);
+        return new App.Response(500, { error: error.message || 'Unknown error' });
       }
+    } else if (req.method === 'DELETE') {
+      try {
+        // Get app version from app context
+        const appVersionId = getAppContext().manifest.meta.version;
+        // Get function name from function context
+        const functionName = functionContext.constructor.name;
 
-      return new App.Response(404, 'Function not found');
+        await this.deleteToolOverrides(appVersionId, functionName);
+        return new App.Response(200, { success: true });
+      } catch (error: any) {
+        logger.error('Error deleting tool overrides:', error);
+        return new App.Response(500, { error: error.message || 'Unknown error' });
+      }
     }
+
+    return new App.Response(405, { error: 'Method not allowed' });
   }
 }
 

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,
   ) {}
 }
 

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([{