@optimizely-opal/opal-tool-ocp-sdk 0.0.0-OCP-1487.6 → 0.0.0-OCP-1487.8

package/src/decorator/Decorator.test.ts

@@ -9,6 +9,9 @@ jest.mock('../service/Service', () => ({
     registerInteraction: jest.fn()
   }
 }));
+
+// Mock base class for testing auto-detection
+class GlobalToolFunction {}
 describe('Decorators', () => {
   beforeEach(() => {
     jest.clearAllMocks();
@@ -657,17 +660,15 @@ describe('Decorators', () => {
   });
 
   describe('global tool registration', () => {
-    it('should register a global tool with isGlobal: true', () => {
-      const config = {
-        name: 'globalTool',
-        description: 'A global tool',
+    it('should auto-detect global tools when class extends GlobalToolFunction', () => {
+      const config: ToolConfig = {
+        name: 'autoGlobalTool',
+        description: 'An auto-detected global tool',
         parameters: [],
-        endpoint: '/global-tool',
-        authRequirements: [],
-        isGlobal: true
+        endpoint: '/auto-global-tool'
       };
 
-      class GlobalTestClass {
+      class TestGlobalClass extends GlobalToolFunction {
         @tool(config)
         public async testTool(): Promise<{ result: string }> {
           return { result: 'global-tool-result' };
@@ -675,16 +676,268 @@ describe('Decorators', () => {
       }
 
       expect(toolsService.registerTool).toHaveBeenCalledWith(
-        'globalTool',
-        'A global tool',
+        'autoGlobalTool',
+        'An auto-detected global tool',
+        expect.any(Function),
+        [],
+        '/auto-global-tool',
+        [],
+        true
+      );
+
+      expect(TestGlobalClass).toBeDefined();
+    });
+
+    it('should register regular tools when class does not extend GlobalToolFunction', () => {
+      const config: ToolConfig = {
+        name: 'regularTool',
+        description: 'A regular tool',
+        parameters: [],
+        endpoint: '/regular-tool'
+      };
+
+      class TestRegularClass {
+        @tool(config)
+        public async testTool(): Promise<{ result: string }> {
+          return { result: 'regular-tool-result' };
+        }
+      }
+
+      expect(toolsService.registerTool).toHaveBeenCalledWith(
+        'regularTool',
+        'A regular tool',
+        expect.any(Function),
+        [],
+        '/regular-tool',
+        [],
+        false
+      );
+
+      expect(TestRegularClass).toBeDefined();
+    });
+
+    it('should register tools as global when import context is set', () => {
+      // Set global import context
+      globalThis.__IMPORT_CONTEXT = 'global';
+
+      const config: ToolConfig = {
+        name: 'importedGlobalTool',
+        description: 'A tool imported as global',
+        parameters: [],
+        endpoint: '/imported-global-tool'
+      };
+
+      class TestImportedClass {
+        @tool(config)
+        public async testTool(): Promise<{ result: string }> {
+          return { result: 'imported-global-tool-result' };
+        }
+      }
+
+      expect(toolsService.registerTool).toHaveBeenCalledWith(
+        'importedGlobalTool',
+        'A tool imported as global',
         expect.any(Function),
         [],
-        '/global-tool',
+        '/imported-global-tool',
         [],
         true
       );
 
-      expect(GlobalTestClass).toBeDefined();
+      // Clean up
+      globalThis.__IMPORT_CONTEXT = undefined;
+      expect(TestImportedClass).toBeDefined();
+    });
+
+    it('should register tools as regular when import context is set to regular', () => {
+      // Set regular import context
+      globalThis.__IMPORT_CONTEXT = 'regular';
+
+      const config: ToolConfig = {
+        name: 'importedRegularTool',
+        description: 'A tool imported as regular',
+        parameters: [],
+        endpoint: '/imported-regular-tool'
+      };
+
+      class TestImportedClass {
+        @tool(config)
+        public async testTool(): Promise<{ result: string }> {
+          return { result: 'imported-regular-tool-result' };
+        }
+      }
+
+      expect(toolsService.registerTool).toHaveBeenCalledWith(
+        'importedRegularTool',
+        'A tool imported as regular',
+        expect.any(Function),
+        [],
+        '/imported-regular-tool',
+        [],
+        false
+      );
+
+      // Clean up
+      globalThis.__IMPORT_CONTEXT = undefined;
+      expect(TestImportedClass).toBeDefined();
+    });
+
+    it('should handle mixed imports - both regular and global tools together', () => {
+      // Test importing regular tools first
+      globalThis.__IMPORT_CONTEXT = 'regular';
+
+      const regularConfig: ToolConfig = {
+        name: 'mixedRegularTool',
+        description: 'A regular tool in mixed scenario',
+        parameters: [],
+        endpoint: '/mixed-regular-tool'
+      };
+
+      class RegularToolClass {
+        @tool(regularConfig)
+        public async regularTool(): Promise<{ result: string }> {
+          return { result: 'mixed-regular-result' };
+        }
+      }
+
+      // Switch to global context
+      globalThis.__IMPORT_CONTEXT = 'global';
+
+      const globalConfig: ToolConfig = {
+        name: 'mixedGlobalTool',
+        description: 'A global tool in mixed scenario',
+        parameters: [],
+        endpoint: '/mixed-global-tool'
+      };
+
+      class GlobalToolClass {
+        @tool(globalConfig)
+        public async globalTool(): Promise<{ result: string }> {
+          return { result: 'mixed-global-result' };
+        }
+      }
+
+      // Clear context
+      globalThis.__IMPORT_CONTEXT = undefined;
+
+      // Verify regular tool was registered as regular
+      expect(toolsService.registerTool).toHaveBeenCalledWith(
+        'mixedRegularTool',
+        'A regular tool in mixed scenario',
+        expect.any(Function),
+        [],
+        '/mixed-regular-tool',
+        [],
+        false
+      );
+
+      // Verify global tool was registered as global
+      expect(toolsService.registerTool).toHaveBeenCalledWith(
+        'mixedGlobalTool',
+        'A global tool in mixed scenario',
+        expect.any(Function),
+        [],
+        '/mixed-global-tool',
+        [],
+        true
+      );
+
+      expect(RegularToolClass).toBeDefined();
+      expect(GlobalToolClass).toBeDefined();
+    });
+
+    it('should handle context switching correctly within same test', () => {
+      let callCount = 0;
+      const originalRegisterTool = jest.mocked(toolsService.registerTool);
+
+      // Track call order and contexts
+      originalRegisterTool.mockImplementation(() => {
+        callCount++;
+        // Store the isGlobal flag from each call for verification
+      });
+
+      // First: Import as regular
+      globalThis.__IMPORT_CONTEXT = 'regular';
+
+      class FirstClass {
+        @tool({
+          name: 'contextTest1',
+          description: 'First context test',
+          parameters: [],
+          endpoint: '/context-test-1'
+        })
+        public async tool1() {
+          return { result: 'test1' };
+        }
+      }
+
+      // Second: Switch to global
+      globalThis.__IMPORT_CONTEXT = 'global';
+
+      class SecondClass {
+        @tool({
+          name: 'contextTest2',
+          description: 'Second context test',
+          parameters: [],
+          endpoint: '/context-test-2'
+        })
+        public async tool2() {
+          return { result: 'test2' };
+        }
+      }
+
+      // Third: Clear context (should fallback to class inheritance)
+      globalThis.__IMPORT_CONTEXT = undefined;
+
+      class ThirdClass {
+        @tool({
+          name: 'contextTest3',
+          description: 'Third context test',
+          parameters: [],
+          endpoint: '/context-test-3'
+        })
+        public async tool3() {
+          return { result: 'test3' };
+        }
+      }
+
+      // Verify the sequence of calls
+      expect(toolsService.registerTool).toHaveBeenNthCalledWith(
+        callCount - 2, // First call
+        'contextTest1',
+        'First context test',
+        expect.any(Function),
+        [],
+        '/context-test-1',
+        [],
+        false // Should be regular
+      );
+
+      expect(toolsService.registerTool).toHaveBeenNthCalledWith(
+        callCount - 1, // Second call
+        'contextTest2',
+        'Second context test',
+        expect.any(Function),
+        [],
+        '/context-test-2',
+        [],
+        true // Should be global
+      );
+
+      expect(toolsService.registerTool).toHaveBeenNthCalledWith(
+        callCount, // Third call
+        'contextTest3',
+        'Third context test',
+        expect.any(Function),
+        [],
+        '/context-test-3',
+        [],
+        false // Should be regular (fallback to class check, ThirdClass doesn't extend GlobalToolFunction)
+      );
+
+      expect(FirstClass).toBeDefined();
+      expect(SecondClass).toBeDefined();
+      expect(ThirdClass).toBeDefined();
     });
   });
 });

package/src/decorator/Decorator.ts

@@ -1,6 +1,44 @@
 import { Parameter, AuthRequirement, ParameterType } from '../types/Models';
 import { toolsService } from '../service/Service';
 
+/**
+ * Global context flag to track import context
+ */
+declare global {
+  var __IMPORT_CONTEXT: 'global' | 'regular' | undefined;
+}
+
+/**
+ * Helper function to check if a class extends GlobalToolFunction
+ */
+function isGlobalToolFunction(constructor: any): boolean {
+  // Walk up the prototype chain to check for GlobalToolFunction
+  let currentConstructor = constructor;
+  while (currentConstructor) {
+    if (currentConstructor.name === 'GlobalToolFunction') {
+      return true;
+    }
+    currentConstructor = Object.getPrototypeOf(currentConstructor);
+  }
+  return false;
+}
+
+/**
+ * Determine if tool should be registered as global based on definition context or import context
+ */
+function shouldRegisterAsGlobal(targetConstructor: any): boolean {
+  // First check if there's an active import context
+  if (globalThis.__IMPORT_CONTEXT === 'global') {
+    return true;
+  }
+  if (globalThis.__IMPORT_CONTEXT === 'regular') {
+    return false;
+  }
+
+  // Fallback to checking where the tool is defined
+  return isGlobalToolFunction(targetConstructor);
+}
+
 /**
  * Configuration for @tool decorator
  */
@@ -10,7 +48,6 @@ export interface ToolConfig {
   parameters: ParameterConfig[];
   authRequirements?: AuthRequirementConfig[];
   endpoint: string;
-  isGlobal?: boolean;
 }
 
 /**
@@ -70,7 +107,10 @@ export function tool(config: ToolConfig) {
       return originalMethod.call(instance, params, authData);
     };
 
-    // Immediately register with global ToolsService
+    // Determine if this tool should be registered as global based on definition or import context
+    const isGlobal = shouldRegisterAsGlobal(target.constructor);
+
+    // Register tool with global flag based on where it's defined or imported
     toolsService.registerTool(
       config.name,
       config.description,
@@ -78,7 +118,7 @@ export function tool(config: ToolConfig) {
       parameters,
       config.endpoint,
       authRequirements,
-      config.isGlobal || false
+      isGlobal
     );
   };
 }

package/src/function/GlobalToolFunction.ts

@@ -1,5 +1,5 @@
 import { GlobalFunction, Response, amendLogContext } from '@zaiusinc/app-sdk';
-import { authorizeGlobalRequest } from '../auth/AuthUtils';
+import { authenticateGlobalRequest, extractAuthData } from '../auth/AuthUtils';
 import { toolsService } from '../service/Service';
 
 /**
@@ -24,7 +24,14 @@ export abstract class GlobalToolFunction extends GlobalFunction {
    * @returns Response as the HTTP response
    */
   public async perform(): Promise<Response> {
-    amendLogContext({ opalThreadId: this.request.headers.get('x-opal-thread-id') || '' });
+    // Extract customer_id from auth data for global context attribution
+    const authInfo = extractAuthData(this.request);
+    const customerId = authInfo?.authData?.credentials?.customer_id;
+
+    amendLogContext({
+      opalThreadId: this.request.headers.get('x-opal-thread-id') || '',
+      customerId: customerId || ''
+    });
 
     if (!(await this.authorizeRequest())) {
       return new Response(403, { error: 'Forbidden' });
@@ -44,6 +51,6 @@ export abstract class GlobalToolFunction extends GlobalFunction {
    * @returns true if authentication succeeds
    */
   private async authorizeRequest(): Promise<boolean> {
-    return await authorizeGlobalRequest(this.request);
+    return await authenticateGlobalRequest(this.request);
   }
 }

package/src/function/ToolFunction.ts

@@ -1,5 +1,5 @@
 import { Function, Response, amendLogContext } from '@zaiusinc/app-sdk';
-import { authorizeRegularRequest } from '../auth/AuthUtils';
+import { authenticateRegularRequest } from '../auth/AuthUtils';
 import { toolsService } from '../service/Service';
 
 /**
@@ -43,6 +43,6 @@ export abstract class ToolFunction extends Function {
    * @returns true if authentication succeeds
    */
   private async authorizeRequest(): Promise<boolean> {
-    return await authorizeRegularRequest(this.request);
+    return await authenticateRegularRequest(this.request);
   }
 }

package/src/service/Service.ts

@@ -89,6 +89,21 @@ export class ToolsService {
   private functions: Map<string, Tool<any>> = new Map();
   private interactions: Map<string, Interaction<any>> = new Map();
 
+  /**
+   * Set the import context for tools that will be imported
+   * @param context The context type ('global' | 'regular')
+   */
+  public setImportContext(context: 'global' | 'regular'): void {
+    globalThis.__IMPORT_CONTEXT = context;
+  }
+
+  /**
+   * Clear the import context after import is complete
+   */
+  public clearImportContext(): void {
+    globalThis.__IMPORT_CONTEXT = undefined;
+  }
+
   /**
    * Enforce OptiID authentication for tools by ensuring OptiID auth requirement is present
    * @param authRequirements Original authentication requirements
@@ -113,6 +128,7 @@ export class ToolsService {
    * @param parameters List of parameters for the tool
    * @param endpoint API endpoint for the tool
    * @param authRequirements Authentication requirements (optional)
+   * @param isGlobal Whether the tool is global
    */
   public registerTool<TAuthData>(
     name: string,
@@ -217,17 +233,18 @@ export class ToolsService {
   /**
    * Handle discovery endpoint requests with context-aware filtering
    * @param functionContext The function context making the request
-   * @returns Response with filtered functions based on context type
+   * @returns Response with filtered functions based on where tools are defined/imported
    */
   private handleDiscovery(functionContext: ToolFunction | GlobalToolFunction): App.Response {
-    // Filter tools based on the function context type
-    const isGlobalFunction = functionContext instanceof GlobalToolFunction;
-    const availableFunctions = Array.from(this.functions.values()).filter((f) => {
-      if (isGlobalFunction) {
-        // Global functions can only see global tools
-        return f.isGlobal;
+    const isGlobalContext = functionContext instanceof GlobalToolFunction;
+
+    const availableFunctions = Array.from(this.functions.values()).filter((tool) => {
+      if (isGlobalContext) {
+        // Global context can only see global tools (defined in or imported into GlobalToolFunction)
+        return tool.isGlobal;
       } else {
-        return !f.isGlobal;
+        // Regular context can only see regular tools (defined in or imported into ToolFunction)
+        return !tool.isGlobal;
       }
     });
 

package/src/utils/ImportUtils.ts

@@ -0,0 +1,45 @@
+import { toolsService } from '../service/Service';
+
+/**
+ * Import a module as global tools
+ * @param modulePath The path to the module to import
+ * @param baseUrl The base URL for resolving relative imports (optional)
+ * @returns The imported module
+ */
+export async function importAsGlobal<T = any>(
+  modulePath: string,
+  baseUrl?: string
+): Promise<T> {
+  try {
+    toolsService.setImportContext('global');
+    // If baseUrl is provided, resolve the module path relative to it
+    // Otherwise, use the modulePath as-is
+    const resolvedPath = baseUrl ? new URL(modulePath, baseUrl).href : modulePath;
+    const module = await import(resolvedPath);
+    return module;
+  } finally {
+    toolsService.clearImportContext();
+  }
+}
+
+/**
+ * Import a module as regular tools
+ * @param modulePath The path to the module to import
+ * @param baseUrl The base URL for resolving relative imports (optional)
+ * @returns The imported module
+ */
+export async function importAsRegular<T = any>(
+  modulePath: string,
+  baseUrl?: string
+): Promise<T> {
+  try {
+    toolsService.setImportContext('regular');
+    // If baseUrl is provided, resolve the module path relative to it
+    // Otherwise, use the modulePath as-is
+    const resolvedPath = baseUrl ? new URL(modulePath, baseUrl).href : modulePath;
+    const module = await import(resolvedPath);
+    return module;
+  } finally {
+    toolsService.clearImportContext();
+  }
+}