@optimizely-opal/opal-tool-ocp-sdk 1.0.0-OCP-1442.5 → 1.0.0-OCP-1449.1

package/src/service/Service.ts

@@ -1,7 +1,8 @@
 /* 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 { logger, Headers, getAppContext } from '@zaiusinc/app-sdk';
 import { ToolFunction } from '../function/ToolFunction';
 import { GlobalToolFunction } from '../function/GlobalToolFunction';
 import { ParameterValidator } from '../validation/ParameterValidator';
@@ -11,13 +12,41 @@ import { ParameterValidator } from '../validation/ParameterValidator';
  */
 const DEFAULT_OPTIID_AUTH = new AuthRequirement('OptiID', 'default', true);
 
+export class NestedInteractions {
+  public constructor(public response: IslandResponse) {
+  }
+}
+
+/**
+ * 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
  */
 export class InteractionResult {
   public constructor(
     public message: string,
-    public link?: string
+    public link?: string,
+    public dispatch_event?: boolean,
+    public interactions?: NestedInteractions
   ) {}
 }
 
@@ -88,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
@@ -104,6 +234,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
@@ -161,70 +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)
-          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']]));
-            }
-          }
+    // 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 new App.Response(500, { error: error.message || 'Unknown error' });
+        // 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;
 
-          // 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);
 
-          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 new App.Response(500, { error: error.message || 'Unknown error' });
+      }
+    }
+    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()) });
+    }
+  }
+
+  /**
+   * 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;
+
+        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/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);
+    });
+  });
+});

package/src/types/ToolError.ts

@@ -0,0 +1,95 @@
+/**
+ * Validation error details
+ */
+export interface ValidationError {
+  field: string;
+  message: string;
+}
+
+/**
+ * Custom error class for tool functions that supports RFC 9457 Problem Details format
+ *
+ * @example
+ * ```typescript
+ * // Throw a 404 error
+ * throw new ToolError('Resource not found', 404, 'The requested task does not exist');
+ *
+ * // Throw a 400 error
+ * throw new ToolError('Invalid input', 400, 'The priority must be "low", "medium", or "high"');
+ *
+ * // Throw a 500 error (default)
+ * throw new ToolError('Database connection failed');
+ *
+ * // Throw a validation error with multiple field errors
+ * 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[];
+
+  /**
+   * 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[]
+  ) {
+    super(message);
+    this.name = 'ToolError';
+    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.message,
+      status: this.status,
+      instance
+    };
+
+    if (this.detail) {
+      problemDetails.detail = this.detail;
+    }
+
+    if (this.errors && this.errors.length > 0) {
+      problemDetails.errors = this.errors;
+    }
+
+    return problemDetails;
+  }
+}