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

package/src/function/ToolFunction.test.ts

@@ -22,12 +22,22 @@ jest.mock('@zaiusinc/app-sdk', () => ({
     }
   },
   Request: jest.fn().mockImplementation(() => ({})),
-  Response: jest.fn().mockImplementation((status, data) => ({
+  Response: jest.fn().mockImplementation((status, data, headers) => ({
     status,
     data,
     bodyJSON: data,
-    bodyAsU8Array: new Uint8Array()
+    bodyAsU8Array: new Uint8Array(),
+    headers
   })),
+  Headers: jest.fn().mockImplementation((entries) => {
+    const headers = new Map();
+    if (entries) {
+      for (const [key, value] of entries) {
+        headers.set(key, value);
+      }
+    }
+    return headers;
+  }),
   amendLogContext: jest.fn(),
   getAppContext: jest.fn(),
   logger: {
@@ -36,20 +46,23 @@ jest.mock('@zaiusinc/app-sdk', () => ({
     warn: jest.fn(),
     debug: jest.fn(),
   },
+  LogVisibility: {
+    Zaius: 'zaius'
+  },
 }));
 
 // Create a concrete implementation for testing
 class TestToolFunction extends ToolFunction {
-  private mockReady: jest.MockedFunction<() => Promise<boolean>>;
+  private mockReady: jest.MockedFunction<() => Promise<{ ready: boolean; reason?: string }>>;
 
   public constructor(request?: any) {
     super(request || {});
     (this as any).request = request;
-    this.mockReady = jest.fn().mockResolvedValue(true);
+    this.mockReady = jest.fn().mockResolvedValue({ ready: true });
   }
 
   // Override the ready method with mock implementation for testing
-  protected ready(): Promise<boolean> {
+  protected ready(): Promise<{ ready: boolean; reason?: string }> {
     return this.mockReady();
   }
 
@@ -161,7 +174,7 @@ describe('ToolFunction', () => {
       const readyRequest = createReadyRequestWithAuth();
 
       toolFunction = new TestToolFunction(readyRequest);
-      toolFunction.getMockReady().mockResolvedValue(true);
+      toolFunction.getMockReady().mockResolvedValue({ ready: true });
 
       // Act
       const result = await toolFunction.perform();
@@ -177,7 +190,7 @@ describe('ToolFunction', () => {
       const readyRequest = createReadyRequestWithAuth();
 
       toolFunction = new TestToolFunction(readyRequest);
-      toolFunction.getMockReady().mockResolvedValue(false);
+      toolFunction.getMockReady().mockResolvedValue({ ready: false });
 
       // Act
       const result = await toolFunction.perform();
@@ -188,6 +201,22 @@ describe('ToolFunction', () => {
       expect(mockProcessRequest).not.toHaveBeenCalled(); // Should not call service
     });
 
+    it('should return ready: false with reason when ready method returns false with reason', async () => {
+      // Arrange
+      const readyRequest = createReadyRequestWithAuth();
+
+      toolFunction = new TestToolFunction(readyRequest);
+      toolFunction.getMockReady().mockResolvedValue({ ready: false, reason: 'Database connection failed' });
+
+      // Act
+      const result = await toolFunction.perform();
+
+      // Assert
+      expect(toolFunction.getMockReady()).toHaveBeenCalledTimes(1);
+      expect(result).toEqual(new Response(200, { ready: false, reason: 'Database connection failed' }));
+      expect(mockProcessRequest).not.toHaveBeenCalled(); // Should not call service
+    });
+
     it('should handle ready method throwing an error', async () => {
       // Arrange
       const readyRequest = createReadyRequestWithAuth();
@@ -248,7 +277,13 @@ describe('ToolFunction', () => {
 
       const result = await toolFunction.perform();
 
-      expect(result).toEqual(new Response(403, { error: 'Forbidden' }));
+      expect(result.status).toBe(403);
+      expect(result.bodyJSON).toEqual({
+        title: 'Forbidden',
+        status: 403,
+        detail: 'Invalid OptiID access token',
+        instance: '/test'
+      });
       expect(mockGetTokenVerifier).toHaveBeenCalled();
       expect(mockTokenVerifier.verify).toHaveBeenCalledWith('valid-access-token');
       expect(mockProcessRequest).not.toHaveBeenCalled();
@@ -274,7 +309,13 @@ describe('ToolFunction', () => {
 
       const result = await toolFunctionWithDifferentOrgId.perform();
 
-      expect(result).toEqual(new Response(403, { error: 'Forbidden' }));
+      expect(result.status).toBe(403);
+      expect(result.bodyJSON).toEqual({
+        title: 'Forbidden',
+        status: 403,
+        detail: 'Organization ID does not match',
+        instance: '/test'
+      });
       expect(mockGetAppContext).toHaveBeenCalled();
       expect(mockProcessRequest).not.toHaveBeenCalled();
     });
@@ -299,7 +340,13 @@ describe('ToolFunction', () => {
 
       const result = await toolFunctionWithoutToken.perform();
 
-      expect(result).toEqual(new Response(403, { error: 'Forbidden' }));
+      expect(result.status).toBe(403);
+      expect(result.bodyJSON).toEqual({
+        title: 'Forbidden',
+        status: 403,
+        detail: 'OptiID access token is required',
+        instance: '/test'
+      });
       expect(mockGetTokenVerifier).not.toHaveBeenCalled();
       expect(mockProcessRequest).not.toHaveBeenCalled();
     });
@@ -324,7 +371,13 @@ describe('ToolFunction', () => {
 
       const result = await toolFunctionWithoutCustomerId.perform();
 
-      expect(result).toEqual(new Response(403, { error: 'Forbidden' }));
+      expect(result.status).toBe(403);
+      expect(result.bodyJSON).toEqual({
+        title: 'Forbidden',
+        status: 403,
+        detail: 'Organization ID is required',
+        instance: '/test'
+      });
       expect(mockGetTokenVerifier).not.toHaveBeenCalled();
       expect(mockProcessRequest).not.toHaveBeenCalled();
     });
@@ -343,7 +396,13 @@ describe('ToolFunction', () => {
 
       const result = await toolFunctionWithoutAuth.perform();
 
-      expect(result).toEqual(new Response(403, { error: 'Forbidden' }));
+      expect(result.status).toBe(403);
+      expect(result.bodyJSON).toEqual({
+        title: 'Forbidden',
+        status: 403,
+        detail: 'Authentication data is required',
+        instance: '/test'
+      });
       expect(mockGetTokenVerifier).not.toHaveBeenCalled();
       expect(mockProcessRequest).not.toHaveBeenCalled();
     });
@@ -354,7 +413,13 @@ describe('ToolFunction', () => {
 
       const result = await toolFunction.perform();
 
-      expect(result).toEqual(new Response(403, { error: 'Forbidden' }));
+      expect(result.status).toBe(403);
+      expect(result.bodyJSON).toEqual({
+        title: 'Forbidden',
+        status: 403,
+        detail: 'Token verification failed',
+        instance: '/test'
+      });
       expect(mockGetTokenVerifier).toHaveBeenCalled();
       expect(mockProcessRequest).not.toHaveBeenCalled();
     });
@@ -371,4 +436,224 @@ describe('ToolFunction', () => {
       expect(toolFunction.getRequest()).toBe(mockRequest);
     });
   });
+
+  describe('internal request authentication', () => {
+    beforeEach(() => {
+      // Reset mocks before each test
+      jest.clearAllMocks();
+      setupAuthMocks();
+    });
+
+    it('should use internal authentication for /overrides endpoint', async () => {
+      const overridesRequest = {
+        path: '/overrides',
+        method: 'DELETE',
+        bodyJSON: {},
+        headers: {
+          get: jest.fn().mockImplementation((name: string) => {
+            if (name === 'Authorization' || name === 'authorization') return 'internal-token';
+            if (name === 'x-opal-thread-id') return 'test-thread-id';
+            return null;
+          })
+        }
+      };
+
+      mockProcessRequest.mockResolvedValue(mockResponse);
+      const toolFunctionOverrides = new TestToolFunction(overridesRequest);
+      const result = await toolFunctionOverrides.perform();
+
+      expect(result).toBe(mockResponse);
+      expect(mockProcessRequest).toHaveBeenCalledWith(overridesRequest, toolFunctionOverrides);
+    });
+
+    it('should throw ToolError when internal authentication fails for /overrides endpoint', async () => {
+      const overridesRequest = {
+        path: '/overrides',
+        method: 'DELETE',
+        bodyJSON: {},
+        headers: {
+          get: jest.fn().mockImplementation((name: string) => {
+            if (name === 'x-opal-thread-id') return 'test-thread-id';
+            return null; // No Authorization header
+          })
+        }
+      };
+
+      const toolFunctionOverrides = new TestToolFunction(overridesRequest);
+      const result = await toolFunctionOverrides.perform();
+
+      expect(result.status).toBe(401);
+      expect(result.bodyJSON).toEqual({
+        title: 'Unauthorized',
+        status: 401,
+        detail: 'Internal request authentication failed',
+        instance: '/overrides'
+      });
+      expect(mockProcessRequest).not.toHaveBeenCalled();
+    });
+
+    it('should use regular authentication for non-overrides endpoints', async () => {
+      const regularRequest = {
+        ...mockRequest,
+        path: '/regular-tool',
+        headers: {
+          get: jest.fn().mockImplementation((name: string) => {
+            if (name === 'x-opal-thread-id') return 'test-thread-id';
+            return null;
+          })
+        }
+      };
+
+      mockProcessRequest.mockResolvedValue(mockResponse);
+      const toolFunctionRegular = new TestToolFunction(regularRequest);
+      const result = await toolFunctionRegular.perform();
+
+      expect(result).toBe(mockResponse);
+      expect(mockProcessRequest).toHaveBeenCalledWith(regularRequest, toolFunctionRegular);
+    });
+
+    it('should handle internal authentication with valid Authorization header', async () => {
+      const overridesRequest = {
+        path: '/overrides',
+        method: 'PATCH',
+        bodyJSON: {
+          functions: [
+            {
+              name: 'test_tool',
+              description: 'Updated description'
+            }
+          ]
+        },
+        headers: {
+          get: jest.fn().mockImplementation((name: string) => {
+            if (name === 'Authorization') return 'valid-internal-token';
+            if (name === 'x-opal-thread-id') return 'test-thread-id';
+            return null;
+          })
+        }
+      };
+
+      mockProcessRequest.mockResolvedValue(mockResponse);
+      const toolFunctionOverrides = new TestToolFunction(overridesRequest);
+      const result = await toolFunctionOverrides.perform();
+
+      expect(result).toBe(mockResponse);
+      expect(mockProcessRequest).toHaveBeenCalledWith(overridesRequest, toolFunctionOverrides);
+    });
+
+    it('should handle internal authentication with lowercase authorization header', async () => {
+      const overridesRequest = {
+        path: '/overrides',
+        method: 'PATCH',
+        bodyJSON: {
+          functions: [
+            {
+              name: 'test_tool',
+              description: 'Updated description'
+            }
+          ]
+        },
+        headers: {
+          get: jest.fn().mockImplementation((name: string) => {
+            if (name === 'authorization') return 'valid-internal-token';
+            if (name === 'x-opal-thread-id') return 'test-thread-id';
+            return null;
+          })
+        }
+      };
+
+      mockProcessRequest.mockResolvedValue(mockResponse);
+      const toolFunctionOverrides = new TestToolFunction(overridesRequest);
+      const result = await toolFunctionOverrides.perform();
+
+      expect(result).toBe(mockResponse);
+      expect(mockProcessRequest).toHaveBeenCalledWith(overridesRequest, toolFunctionOverrides);
+    });
+
+    it('should fail internal authentication when token verification fails', async () => {
+      // Mock token verifier to return false for invalid token
+      mockTokenVerifier.verify.mockResolvedValue(false);
+
+      const overridesRequest = {
+        path: '/overrides',
+        method: 'DELETE',
+        bodyJSON: {},
+        headers: {
+          get: jest.fn().mockImplementation((name: string) => {
+            if (name === 'Authorization') return 'invalid-token';
+            if (name === 'x-opal-thread-id') return 'test-thread-id';
+            return null;
+          })
+        }
+      };
+
+      const toolFunctionOverrides = new TestToolFunction(overridesRequest);
+      const result = await toolFunctionOverrides.perform();
+
+      expect(result.status).toBe(401);
+      expect(result.bodyJSON).toEqual({
+        title: 'Unauthorized',
+        status: 401,
+        detail: 'Internal request authentication failed',
+        instance: '/overrides'
+      });
+      expect(mockProcessRequest).not.toHaveBeenCalled();
+    });
+
+    it('should fail internal authentication when token verifier throws error', async () => {
+      // Mock token verifier to throw an error
+      mockTokenVerifier.verify.mockRejectedValue(new Error('Token service unavailable'));
+
+      const overridesRequest = {
+        path: '/overrides',
+        method: 'DELETE',
+        bodyJSON: {},
+        headers: {
+          get: jest.fn().mockImplementation((name: string) => {
+            if (name === 'Authorization') return 'some-token';
+            if (name === 'x-opal-thread-id') return 'test-thread-id';
+            return null;
+          })
+        }
+      };
+
+      const toolFunctionOverrides = new TestToolFunction(overridesRequest);
+      const result = await toolFunctionOverrides.perform();
+
+      expect(result.status).toBe(401);
+      expect(result.bodyJSON).toEqual({
+        title: 'Unauthorized',
+        status: 401,
+        detail: 'Internal request authentication failed',
+        instance: '/overrides'
+      });
+      expect(mockProcessRequest).not.toHaveBeenCalled();
+    });
+
+    it('should fail internal authentication when headers object is missing', async () => {
+      const overridesRequest = {
+        path: '/overrides',
+        method: 'DELETE',
+        bodyJSON: {},
+        headers: {
+          get: jest.fn().mockImplementation((name: string) => {
+            if (name === 'x-opal-thread-id') return 'test-thread-id';
+            return null;
+          })
+        }
+      };
+
+      const toolFunctionOverrides = new TestToolFunction(overridesRequest);
+      const result = await toolFunctionOverrides.perform();
+
+      expect(result.status).toBe(401);
+      expect(result.bodyJSON).toEqual({
+        title: 'Unauthorized',
+        status: 401,
+        detail: 'Internal request authentication failed',
+        instance: '/overrides'
+      });
+      expect(mockProcessRequest).not.toHaveBeenCalled();
+    });
+  });
 });

package/src/function/ToolFunction.ts

@@ -1,6 +1,9 @@
-import { Function, Response, amendLogContext } from '@zaiusinc/app-sdk';
-import { authenticateRegularRequest } from '../auth/AuthUtils';
+import { Function, Response, Headers, amendLogContext } from '@zaiusinc/app-sdk';
+import { authenticateRegularRequest, authenticateInternalRequest } from '../auth/AuthUtils';
 import { toolsService } from '../service/Service';
+import { ToolLogger } from '../logging/ToolLogger';
+import { ToolError } from '../types/ToolError';
+import { ReadyResponse } from '../types/Models';
 
 /**
  * Abstract base class for tool-based function execution
@@ -12,27 +15,66 @@ export abstract class ToolFunction extends Function {
    * Override this method to implement any required credentials and/or other configuration
    * exist and are valid. Reasonable caching should be utilized to prevent excessive requests to external resources.
    * @async
-   * @returns true if the opal function is ready to use
+   * @returns ReadyResponse containing ready status and optional reason when not ready
    */
-  protected ready(): Promise<boolean> {
-    return Promise.resolve(true);
+  protected ready(): Promise<ReadyResponse | boolean> {
+    return Promise.resolve({ ready: true });
   }
 
   /**
-   * Process the incoming request using the tools service
+   * Process the incoming request with logging
    *
    * @returns Response as the HTTP response
    */
   public async perform(): Promise<Response> {
+    const startTime = Date.now();
     amendLogContext({ opalThreadId: this.request.headers.get('x-opal-thread-id') || '' });
-    if (!(await this.authorizeRequest())) {
-      return new Response(403, { error: 'Forbidden' });
+
+    ToolLogger.logRequest(this.request);
+
+    const response = await this.handleRequest();
+
+    ToolLogger.logResponse(this.request, response, Date.now() - startTime);
+    return response;
+  }
+
+  /**
+   * Handle the core request processing logic
+   *
+   * @returns Response as the HTTP response
+   */
+  private async handleRequest(): Promise<Response> {
+    try {
+      await this.authorizeRequest();
+    } catch (error) {
+      if (error instanceof ToolError) {
+        return new Response(
+          error.status,
+          error.toProblemDetails(this.request.path),
+          new Headers([['content-type', 'application/problem+json']])
+        );
+      }
+      // Fallback for unexpected errors
+      return new Response(
+        500,
+        {
+          title: 'Internal Server Error',
+          status: 500,
+          detail: 'An unexpected error occurred during authentication',
+          instance: this.request.path
+        },
+        new Headers([['content-type', 'application/problem+json']])
+      );
     }
 
     if (this.request.path === '/ready') {
-      const isReady = await this.ready();
-      return new Response(200, { ready: isReady });
+      const readyResult = await this.ready();
+      const readyResponse = typeof readyResult === 'boolean'
+        ? { ready: readyResult }
+        : readyResult;
+      return new Response(200, readyResponse);
     }
+
     // Pass 'this' as context so decorated methods can use the existing instance
     return toolsService.processRequest(this.request, this);
   }
@@ -40,9 +82,15 @@ export abstract class ToolFunction extends Function {
   /**
    * Authenticate the incoming request by validating the OptiID token and organization ID
    *
-   * @returns true if authentication succeeds
+   * @throws {ToolError} If authentication fails
    */
-  private async authorizeRequest(): Promise<boolean> {
-    return await authenticateRegularRequest(this.request);
+  private async authorizeRequest(): Promise<void> {
+    // Use internal authentication for overrides endpoint (header-based token)
+    if (this.request.path === '/overrides') {
+      await authenticateInternalRequest(this.request);
+    } else {
+      // Use regular authentication for other endpoints (body-based token with org validation)
+      await authenticateRegularRequest(this.request);
+    }
   }
 }

package/src/index.ts

@@ -1,6 +1,7 @@
 export * from './function/ToolFunction';
 export * from './function/GlobalToolFunction';
 export * from './types/Models';
+export * from './types/ToolError';
 export * from './decorator/Decorator';
 export * from './auth/TokenVerifier';
-export { Tool, Interaction, InteractionResult } from './service/Service';
+export { Tool, Interaction, InteractionResult, NestedInteractions } from './service/Service';