@optimizely-opal/opal-tool-ocp-sdk 0.0.0-OCP-1487.1

package/src/decorator/Decorator.ts

@@ -0,0 +1,111 @@
+import { Parameter, AuthRequirement, ParameterType } from '../types/Models';
+import { toolsService } from '../service/Service';
+
+/**
+ * Configuration for @tool decorator
+ */
+export interface ToolConfig {
+  name: string;
+  description: string;
+  parameters: ParameterConfig[];
+  authRequirements?: AuthRequirementConfig[];
+  endpoint: string;
+}
+
+/**
+ * Parameter configuration for decorators
+ */
+export interface ParameterConfig {
+  name: string;
+  type: ParameterType;
+  description: string;
+  required: boolean;
+}
+
+/**
+ * AuthRequirement configuration for decorators
+ */
+export interface AuthRequirementConfig {
+  provider: string;
+  scopeBundle: string;
+  required?: boolean;
+}
+
+/**
+ * Configuration for @interaction decorator
+ */
+export interface InteractionConfig {
+  name: string;
+  endpoint: string;
+}
+
+/**
+ * Decorator for registering tool functions
+ * Immediately registers the tool with the global ToolsService
+ * The handler will have access to 'this' context when called
+ */
+export function tool(config: ToolConfig) {
+  return function(target: any, _propertyKey: string, descriptor: PropertyDescriptor) {
+    // Convert parameter configs to Parameter instances
+    const parameters = (config.parameters || []).map((p) =>
+      new Parameter(p.name, p.type, p.description, p.required)
+    );
+
+    // Convert auth requirement configs to AuthRequirement instances
+    const authRequirements = (config.authRequirements || []).map((a) =>
+      new AuthRequirement(a.provider, a.scopeBundle, a.required)
+    );
+
+    const originalMethod = descriptor.value;
+
+    const boundHandler = function(functionContext: any, params: any, authData: any) {
+      // Check if we're being called from within a ToolFunction instance context
+      // If so, use that instance; otherwise create a new one
+      const instance = (functionContext && functionContext instanceof target.constructor) ?
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+        functionContext : new target.constructor();
+
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+      return originalMethod.call(instance, params, authData);
+    };
+
+    // Immediately register with global ToolsService
+    toolsService.registerTool(
+      config.name,
+      config.description,
+      boundHandler,
+      parameters,
+      config.endpoint,
+      authRequirements
+    );
+  };
+}
+
+/**
+ * Decorator for registering interaction functions
+ * Immediately registers the interaction with the global ToolsService
+ * The handler will have access to 'this' context when called
+ */
+export function interaction(config: InteractionConfig) {
+  return function(target: any, _propertyKey: string, descriptor: PropertyDescriptor) {
+    const originalMethod = descriptor.value;
+
+    const boundHandler = function(functionContext: any, data: any, authData?: any) {
+      // Check if we're being called from within a ToolFunction instance context
+      // If so, use that instance; otherwise create a new one
+      const instance = (functionContext && functionContext instanceof target.constructor) ?
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+        functionContext : new target.constructor();
+
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+      return originalMethod.call(instance, data, authData);
+    };
+
+    // Immediately register with global ToolsService
+    toolsService.registerInteraction(
+      config.name,
+      boundHandler,
+      config.endpoint
+    );
+  };
+}

package/src/function/GlobalToolFunction.test.ts

@@ -0,0 +1,505 @@
+import { GlobalToolFunction } from './GlobalToolFunction';
+import { toolsService } from '../service/Service';
+import { Response, getAppContext } from '@zaiusinc/app-sdk';
+import { getTokenVerifier } from '../auth/TokenVerifier';
+
+// Mock the dependencies
+jest.mock('../service/Service', () => ({
+  toolsService: {
+    processRequest: jest.fn(),
+  },
+}));
+
+jest.mock('../auth/TokenVerifier', () => ({
+  getTokenVerifier: jest.fn(),
+}));
+
+jest.mock('@zaiusinc/app-sdk', () => ({
+  GlobalFunction: class {
+    protected request: any;
+    public constructor(_name?: string) {
+      this.request = {};
+    }
+  },
+  Request: jest.fn().mockImplementation(() => ({})),
+  Response: jest.fn().mockImplementation((status, data) => ({
+    status,
+    data,
+    bodyJSON: data,
+    bodyAsU8Array: new Uint8Array()
+  })),
+  amendLogContext: jest.fn(),
+  getAppContext: jest.fn(),
+  logger: {
+    info: jest.fn(),
+    error: jest.fn(),
+    warn: jest.fn(),
+    debug: jest.fn(),
+  },
+}));
+
+// Create a concrete implementation for testing
+class TestGlobalToolFunction extends GlobalToolFunction {
+  private mockReady: jest.MockedFunction<() => Promise<boolean>>;
+
+  public constructor(request?: any) {
+    super(request || {});
+    (this as any).request = request;
+    this.mockReady = jest.fn().mockResolvedValue(true);
+  }
+
+  // Override the ready method with mock implementation for testing
+  protected ready(): Promise<boolean> {
+    return this.mockReady();
+  }
+
+  public getRequest() {
+    return (this as any).request;
+  }
+
+  public getMockReady() {
+    return this.mockReady;
+  }
+}
+
+describe('GlobalToolFunction', () => {
+  let mockRequest: any;
+  let mockResponse: Response;
+  let globalToolFunction: TestGlobalToolFunction;
+  let mockProcessRequest: jest.MockedFunction<typeof toolsService.processRequest>;
+  let mockGetTokenVerifier: jest.MockedFunction<typeof getTokenVerifier>;
+  let mockGetAppContext: jest.MockedFunction<typeof getAppContext>;
+  let mockTokenVerifier: jest.Mocked<{
+    verify: (token: string) => Promise<any>;
+  }>;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+
+    // Create mock token verifier
+    mockTokenVerifier = {
+      verify: jest.fn(),
+    };
+
+    // Setup the mocks
+    mockProcessRequest = jest.mocked(toolsService.processRequest);
+    mockGetTokenVerifier = jest.mocked(getTokenVerifier);
+    mockGetAppContext = jest.mocked(getAppContext);
+
+    mockGetTokenVerifier.mockResolvedValue(mockTokenVerifier as any);
+    mockGetAppContext.mockReturnValue({
+      account: {
+        organizationId: 'app-org-123'
+      }
+    } as any);
+
+    // Create mock request with bodyJSON structure
+    // Note: Global functions don't validate customer_id, so it can be different or missing
+    mockRequest = {
+      headers: new Map(),
+      method: 'POST',
+      path: '/test',
+      bodyJSON: {
+        parameters: {
+          task_id: 'task-123',
+          content_id: 'content-456'
+        },
+        auth: {
+          provider: 'OptiID',
+          credentials: {
+            token_type: 'Bearer',
+            access_token: 'valid-access-token',
+            org_sso_id: 'org-sso-123',
+            user_id: 'user-456',
+            instance_id: 'instance-789',
+            customer_id: 'any-org-123', // Can be different from app org for global functions
+            product_sku: 'OPAL'
+          }
+        },
+        environment: {
+          execution_mode: 'headless'
+        }
+      }
+    };
+
+    mockResponse = {} as Response;
+    globalToolFunction = new TestGlobalToolFunction(mockRequest);
+  });
+
+  // Helper function to create a ready request with valid auth
+  const createReadyRequestWithAuth = () => ({
+    headers: new Map(),
+    method: 'GET',
+    path: '/ready',
+    bodyJSON: {
+      auth: {
+        provider: 'OptiID',
+        credentials: {
+          access_token: 'valid-token',
+          customer_id: 'any-org-123' // Can be any org for global functions
+        }
+      }
+    }
+  });
+
+  // Helper function to create a discovery request
+  const createDiscoveryRequest = () => ({
+    headers: new Map(),
+    method: 'GET',
+    path: '/discovery'
+  });
+
+  // Helper function to setup authorization mocks to pass
+  const setupAuthMocks = () => {
+    mockTokenVerifier.verify.mockResolvedValue(true);
+  };
+
+  describe('/discovery endpoint', () => {
+    it('should allow discovery endpoint without authentication', async () => {
+      // Arrange
+      const discoveryRequest = createDiscoveryRequest();
+      globalToolFunction = new TestGlobalToolFunction(discoveryRequest);
+      mockProcessRequest.mockResolvedValue(mockResponse);
+
+      // Act
+      const result = await globalToolFunction.perform();
+
+      // Assert
+      expect(result).toBe(mockResponse);
+      expect(mockGetTokenVerifier).not.toHaveBeenCalled(); // Should not verify token for discovery
+      expect(mockProcessRequest).toHaveBeenCalledWith(discoveryRequest, globalToolFunction);
+    });
+  });
+
+  describe('/ready endpoint', () => {
+    beforeEach(() => {
+      setupAuthMocks();
+    });
+
+    it('should return ready: true when ready method returns true', async () => {
+      // Arrange
+      const readyRequest = createReadyRequestWithAuth();
+      globalToolFunction = new TestGlobalToolFunction(readyRequest);
+      globalToolFunction.getMockReady().mockResolvedValue(true);
+
+      // Act
+      const result = await globalToolFunction.perform();
+
+      // Assert
+      expect(globalToolFunction.getMockReady()).toHaveBeenCalledTimes(1);
+      expect(result).toEqual(new Response(200, { ready: true }));
+      expect(mockProcessRequest).not.toHaveBeenCalled(); // Should not call service
+    });
+
+    it('should return ready: false when ready method returns false', async () => {
+      // Arrange
+      const readyRequest = createReadyRequestWithAuth();
+      globalToolFunction = new TestGlobalToolFunction(readyRequest);
+      globalToolFunction.getMockReady().mockResolvedValue(false);
+
+      // Act
+      const result = await globalToolFunction.perform();
+
+      // Assert
+      expect(globalToolFunction.getMockReady()).toHaveBeenCalledTimes(1);
+      expect(result).toEqual(new Response(200, { ready: false }));
+      expect(mockProcessRequest).not.toHaveBeenCalled(); // Should not call service
+    });
+
+    it('should handle ready method throwing an error', async () => {
+      // Arrange
+      const readyRequest = createReadyRequestWithAuth();
+      globalToolFunction = new TestGlobalToolFunction(readyRequest);
+      globalToolFunction.getMockReady().mockRejectedValue(new Error('Ready check failed'));
+
+      // Act & Assert
+      await expect(globalToolFunction.perform()).rejects.toThrow('Ready check failed');
+      expect(globalToolFunction.getMockReady()).toHaveBeenCalledTimes(1);
+      expect(mockProcessRequest).not.toHaveBeenCalled(); // Should not call service
+    });
+
+    it('should use default ready implementation when not overridden', async () => {
+      // Create a class that doesn't override ready method
+      class DefaultReadyGlobalToolFunction extends GlobalToolFunction {
+        public constructor(request?: any) {
+          super(request || {});
+          (this as any).request = request;
+        }
+
+        public getRequest() {
+          return (this as any).request;
+        }
+      }
+
+      // Arrange
+      const readyRequest = createReadyRequestWithAuth();
+      const defaultGlobalToolFunction = new DefaultReadyGlobalToolFunction(readyRequest);
+
+      // Act
+      const result = await defaultGlobalToolFunction.perform();
+
+      // Assert - Default implementation should return true
+      expect(result).toEqual(new Response(200, { ready: true }));
+      expect(mockProcessRequest).not.toHaveBeenCalled(); // Should not call service
+    });
+
+    it('should allow ready endpoint without authentication', async () => {
+      // Arrange
+      const readyRequestWithoutAuth = {
+        headers: new Map(),
+        method: 'GET',
+        path: '/ready'
+      };
+      globalToolFunction = new TestGlobalToolFunction(readyRequestWithoutAuth);
+      globalToolFunction.getMockReady().mockResolvedValue(true);
+
+      // Act
+      const result = await globalToolFunction.perform();
+
+      // Assert
+      expect(result).toEqual(new Response(200, { ready: true }));
+      expect(mockGetTokenVerifier).not.toHaveBeenCalled(); // Should not verify token for ready
+      expect(mockProcessRequest).not.toHaveBeenCalled(); // Should not call service
+    });
+  });
+
+  describe('perform', () => {
+    it('should execute successfully with valid token (no organization validation)', async () => {
+      // Setup mock token verifier to return true for valid token
+      mockTokenVerifier.verify.mockResolvedValue(true);
+      mockProcessRequest.mockResolvedValue(mockResponse);
+
+      const result = await globalToolFunction.perform();
+
+      expect(result).toBe(mockResponse);
+      expect(mockGetTokenVerifier).toHaveBeenCalled();
+      expect(mockTokenVerifier.verify).toHaveBeenCalledWith('valid-access-token');
+      // Note: getAppContext should NOT be called for global functions
+      expect(mockGetAppContext).not.toHaveBeenCalled();
+      expect(mockProcessRequest).toHaveBeenCalledWith(mockRequest, globalToolFunction);
+    });
+
+    it('should execute successfully even with different organization ID', async () => {
+      // Update mock request with different customer_id (should still work for global functions)
+      const requestWithDifferentOrgId = {
+        ...mockRequest,
+        bodyJSON: {
+          ...mockRequest.bodyJSON,
+          auth: {
+            ...mockRequest.bodyJSON.auth,
+            credentials: {
+              ...mockRequest.bodyJSON.auth.credentials,
+              customer_id: 'completely-different-org-456'
+            }
+          }
+        }
+      };
+
+      const globalToolFunctionWithDifferentOrgId = new TestGlobalToolFunction(requestWithDifferentOrgId);
+      mockTokenVerifier.verify.mockResolvedValue(true);
+      mockProcessRequest.mockResolvedValue(mockResponse);
+
+      const result = await globalToolFunctionWithDifferentOrgId.perform();
+
+      expect(result).toBe(mockResponse);
+      expect(mockGetTokenVerifier).toHaveBeenCalled();
+      expect(mockTokenVerifier.verify).toHaveBeenCalledWith('valid-access-token');
+      // Note: Should NOT validate organization ID for global functions
+      expect(mockGetAppContext).not.toHaveBeenCalled();
+      expect(mockProcessRequest).toHaveBeenCalledWith(requestWithDifferentOrgId, globalToolFunctionWithDifferentOrgId);
+    });
+
+    it('should execute successfully even without customer_id', async () => {
+      // Create request without customer_id (should still work for global functions)
+      const requestWithoutCustomerId = {
+        ...mockRequest,
+        bodyJSON: {
+          ...mockRequest.bodyJSON,
+          auth: {
+            ...mockRequest.bodyJSON.auth,
+            credentials: {
+              ...mockRequest.bodyJSON.auth.credentials,
+              customer_id: undefined
+            }
+          }
+        }
+      };
+
+      const globalToolFunctionWithoutCustomerId = new TestGlobalToolFunction(requestWithoutCustomerId);
+      mockTokenVerifier.verify.mockResolvedValue(true);
+      mockProcessRequest.mockResolvedValue(mockResponse);
+
+      const result = await globalToolFunctionWithoutCustomerId.perform();
+
+      expect(result).toBe(mockResponse);
+      expect(mockGetTokenVerifier).toHaveBeenCalled();
+      expect(mockTokenVerifier.verify).toHaveBeenCalledWith('valid-access-token');
+      expect(mockGetAppContext).not.toHaveBeenCalled();
+      expect(mockProcessRequest).toHaveBeenCalledWith(requestWithoutCustomerId, globalToolFunctionWithoutCustomerId);
+    });
+
+    it('should return 403 response with invalid token', async () => {
+      // Setup mock token verifier to return false
+      mockTokenVerifier.verify.mockResolvedValue(false);
+
+      const result = await globalToolFunction.perform();
+
+      expect(result).toEqual(new Response(403, { error: 'Forbidden' }));
+      expect(mockGetTokenVerifier).toHaveBeenCalled();
+      expect(mockTokenVerifier.verify).toHaveBeenCalledWith('valid-access-token');
+      expect(mockProcessRequest).not.toHaveBeenCalled();
+    });
+
+    it('should return 403 response when access token is missing', async () => {
+      // Create request without access token
+      const requestWithoutToken = {
+        ...mockRequest,
+        bodyJSON: {
+          ...mockRequest.bodyJSON,
+          auth: {
+            ...mockRequest.bodyJSON.auth,
+            credentials: {
+              ...mockRequest.bodyJSON.auth.credentials,
+              access_token: undefined
+            }
+          }
+        }
+      };
+
+      const globalToolFunctionWithoutToken = new TestGlobalToolFunction(requestWithoutToken);
+
+      const result = await globalToolFunctionWithoutToken.perform();
+
+      expect(result).toEqual(new Response(403, { error: 'Forbidden' }));
+      expect(mockGetTokenVerifier).not.toHaveBeenCalled();
+      expect(mockProcessRequest).not.toHaveBeenCalled();
+    });
+
+    it('should return 403 response when provider is not OptiID', async () => {
+      // Create request with different provider
+      const requestWithDifferentProvider = {
+        ...mockRequest,
+        bodyJSON: {
+          ...mockRequest.bodyJSON,
+          auth: {
+            ...mockRequest.bodyJSON.auth,
+            provider: 'SomeOtherProvider'
+          }
+        }
+      };
+
+      const globalToolFunctionWithDifferentProvider = new TestGlobalToolFunction(requestWithDifferentProvider);
+
+      const result = await globalToolFunctionWithDifferentProvider.perform();
+
+      expect(result).toEqual(new Response(403, { error: 'Forbidden' }));
+      expect(mockGetTokenVerifier).not.toHaveBeenCalled();
+      expect(mockProcessRequest).not.toHaveBeenCalled();
+    });
+
+    it('should return 403 response when auth structure is missing', async () => {
+      // Create request without auth structure
+      const requestWithoutAuth = {
+        ...mockRequest,
+        bodyJSON: {
+          parameters: mockRequest.bodyJSON.parameters,
+          environment: mockRequest.bodyJSON.environment
+        }
+      };
+
+      const globalToolFunctionWithoutAuth = new TestGlobalToolFunction(requestWithoutAuth);
+
+      const result = await globalToolFunctionWithoutAuth.perform();
+
+      expect(result).toEqual(new Response(403, { error: 'Forbidden' }));
+      expect(mockGetTokenVerifier).not.toHaveBeenCalled();
+      expect(mockProcessRequest).not.toHaveBeenCalled();
+    });
+
+    it('should return 403 response when token verifier initialization fails', async () => {
+      // Setup mock to fail during token verifier initialization
+      mockGetTokenVerifier.mockRejectedValue(new Error('Failed to initialize token verifier'));
+
+      const result = await globalToolFunction.perform();
+
+      expect(result).toEqual(new Response(403, { error: 'Forbidden' }));
+      expect(mockGetTokenVerifier).toHaveBeenCalled();
+      expect(mockProcessRequest).not.toHaveBeenCalled();
+    });
+
+    it('should return 403 response when token validation throws an error', async () => {
+      // Setup mock token verifier to throw an error
+      mockTokenVerifier.verify.mockRejectedValue(new Error('Token validation failed'));
+
+      const result = await globalToolFunction.perform();
+
+      expect(result).toEqual(new Response(403, { error: 'Forbidden' }));
+      expect(mockGetTokenVerifier).toHaveBeenCalled();
+      expect(mockTokenVerifier.verify).toHaveBeenCalledWith('valid-access-token');
+      expect(mockProcessRequest).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('inheritance', () => {
+    it('should be an instance of GlobalFunction', () => {
+      // Assert
+      expect(globalToolFunction).toBeInstanceOf(GlobalToolFunction);
+    });
+
+    it('should have access to the request property', () => {
+      // Assert
+      expect(globalToolFunction.getRequest()).toBe(mockRequest);
+    });
+  });
+
+  describe('authentication differences from ToolFunction', () => {
+    it('should NOT validate organization ID (unlike ToolFunction)', async () => {
+      // This test demonstrates the key difference between GlobalToolFunction and ToolFunction
+      // GlobalToolFunction should work with any customer_id, while ToolFunction requires matching org ID
+
+      const requestWithRandomOrgId = {
+        ...mockRequest,
+        bodyJSON: {
+          ...mockRequest.bodyJSON,
+          auth: {
+            ...mockRequest.bodyJSON.auth,
+            credentials: {
+              ...mockRequest.bodyJSON.auth.credentials,
+              customer_id: 'random-org-999' // This would fail in ToolFunction but should work here
+            }
+          }
+        }
+      };
+
+      const globalToolFunctionWithRandomOrgId = new TestGlobalToolFunction(requestWithRandomOrgId);
+      mockTokenVerifier.verify.mockResolvedValue(true);
+      mockProcessRequest.mockResolvedValue(mockResponse);
+
+      const result = await globalToolFunctionWithRandomOrgId.perform();
+
+      // Should succeed even with different org ID
+      expect(result).toBe(mockResponse);
+      expect(mockGetTokenVerifier).toHaveBeenCalled();
+      expect(mockTokenVerifier.verify).toHaveBeenCalledWith('valid-access-token');
+      // Crucially: getAppContext should NOT be called (no org validation)
+      expect(mockGetAppContext).not.toHaveBeenCalled();
+      expect(mockProcessRequest).toHaveBeenCalledWith(requestWithRandomOrgId, globalToolFunctionWithRandomOrgId);
+    });
+
+    it('should only require valid OptiID token (no organization constraints)', async () => {
+      // Test that only token validation is performed, no org validation
+      mockTokenVerifier.verify.mockResolvedValue(true);
+      mockProcessRequest.mockResolvedValue(mockResponse);
+
+      const result = await globalToolFunction.perform();
+
+      expect(result).toBe(mockResponse);
+      expect(mockGetTokenVerifier).toHaveBeenCalled();
+      expect(mockTokenVerifier.verify).toHaveBeenCalledWith('valid-access-token');
+
+      // Key assertion: getAppContext should never be called for global functions
+      expect(mockGetAppContext).not.toHaveBeenCalled();
+      expect(mockProcessRequest).toHaveBeenCalledWith(mockRequest, globalToolFunction);
+    });
+  });
+});

package/src/function/GlobalToolFunction.ts

@@ -0,0 +1,61 @@
+import { GlobalFunction, Response, amendLogContext } from '@zaiusinc/app-sdk';
+import { AuthUtils } from '../auth/AuthUtils';
+import { toolsService } from '../service/Service';
+
+/**
+ * Abstract base class for global tool-based function execution
+ * Provides a standard interface for processing requests through registered tools
+ */
+export abstract class GlobalToolFunction extends GlobalFunction {
+
+  /**
+   * 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
+   */
+  protected ready(): Promise<boolean> {
+    return Promise.resolve(true);
+  }
+
+  /**
+   * Process the incoming request using the tools service
+   *
+   * @returns Response as the HTTP response
+   */
+  public async perform(): Promise<Response> {
+    amendLogContext({ opalThreadId: this.request.headers.get('x-opal-thread-id') || '' });
+
+    if (!(await this.authorizeRequest())) {
+      return new Response(403, { error: 'Forbidden' });
+    }
+
+    if (this.request.path === '/ready') {
+      const isReady = await this.ready();
+      return new Response(200, { ready: isReady });
+    }
+
+    return toolsService.processRequest(this.request, this);
+  }
+
+  /**
+   * Authenticate the incoming request by validating only the OptiID token
+   *
+   * @param request - The incoming request
+   * @returns true if authentication succeeds
+   */
+  private async authorizeRequest(): Promise<boolean> {
+    if (this.request.path === '/discovery' || this.request.path === '/ready') {
+      return true;
+    }
+
+    const authInfo = AuthUtils.extractAuthData(this.request);
+    if (!authInfo) {
+      return false;
+    }
+
+    const { accessToken } = authInfo;
+
+    return await AuthUtils.validateAccessToken(accessToken);
+  }
+}