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

package/README.md

@@ -7,8 +7,9 @@ A TypeScript SDK for building Opal tools in Optimizely Connect Platform. This SD
 ## Features
 
 - 🎯 **Decorator-based Tool Registration** - Use `@tool` and `@interaction` decorators to easily register functions
+- 🌐 **Global and Regular Tools** - Support for both organization-scoped and global tools
 - 🔧 **Type-safe Development** - Full TypeScript support with comprehensive type definitions  
-- 🏗️ **Abstract Base Classes** - Extend `ToolFunction` for standardized request processing
+- 🏗️ **Abstract Base Classes** - Extend `ToolFunction` or `GlobalToolFunction` for standardized request processing
 - 🔐 **Authentication Support** - OptiID authentication
 - 🛡️ **Authorization Support** - OptiID token tool authorization
 - 📝 **Parameter Validation** - Define and validate tool parameters with types
@@ -28,7 +29,14 @@ yarn add @optimizely-opal/opal-tool-ocp-sdk
 
 ## Quick Start
 
-Create a tool function class by extending `ToolFunction` and registering your tools and interactions:
+The SDK supports two types of functions:
+
+- **Regular Functions** (`ToolFunction`) - Organization-scoped tools that validate customer organization IDs
+- **Global Functions** (`GlobalToolFunction`) - Platform-wide tools that work across all organizations
+
+### Regular Tool Function
+
+Create a tool function class by extending `ToolFunction` for organization-scoped tools:
 
 ```typescript
 import { ToolFunction, tool, interaction, ParameterType, InteractionResult, OptiIdAuthData } from '@optimizely-opal/opal-tool-ocp-sdk';
@@ -89,12 +97,12 @@ export class MyToolFunction extends ToolFunction {
       throw new Error('OptiID authentication required');
     }
 
-    const { customerId, instanceId, accessToken } = authData.credentials;
+    const { customer_id, instance_id, access_token } = authData.credentials;
     return {
       id: '456',
       title: params.title,
-      customerId,
-      instanceId
+      customer_id,
+      instance_id
     };
   }
 
@@ -112,7 +120,48 @@ export class MyToolFunction extends ToolFunction {
 }
 ```
 
-Your function class inherits a `perform()` method from `ToolFunction` that serves as the main entry point for handling all incoming requests. When called, the SDK automatically:
+### Global Tool Function
+
+Create a global tool function by extending `GlobalToolFunction` for platform-wide tools:
+
+```typescript
+import { GlobalToolFunction, tool, interaction, ParameterType, InteractionResult, OptiIdAuthData } from '@optimizely-opal/opal-tool-ocp-sdk';
+
+export class MyGlobalToolFunction extends GlobalToolFunction {
+
+  @tool({
+    name: 'global_utility',
+    description: 'A utility tool available to all organizations',
+    endpoint: '/global-utility',
+    parameters: [
+      {
+        name: 'operation',
+        type: ParameterType.String,
+        description: 'The operation to perform',
+        required: true
+      }
+    ],
+    isGlobal: true  // Mark this tool as global
+  })
+  async globalUtility(params: { operation: string }, authData?: OptiIdAuthData) {
+    return {
+      result: `Performed ${params.operation} globally`,
+      organizationId: authData?.credentials.customer_id || 'unknown'
+    };
+  }
+}
+```
+
+### Function Types and Tool Discovery
+
+The SDK provides intelligent tool discovery based on function type:
+
+- **Regular Functions** (`ToolFunction`): Can only discover and access non-global tools
+- **Global Functions** (`GlobalToolFunction`): Can only discover and access global tools (marked with `isGlobal: true`)
+
+This ensures proper isolation between global platform tools and organization-specific tools.
+
+Your function class inherits a `perform()` method from `ToolFunction` or `GlobalToolFunction` that serves as the main entry point for handling all incoming requests. When called, the SDK automatically:
 
 - **Routes requests** to your registered tools and interactions based on endpoints
 - **Handles authentication** and OptiID token validation before calling your methods  
@@ -129,6 +178,24 @@ Tools are functions that can be discovered and executed through the OCP platform
 - Define parameters with types and validation
 - Can require authentication
 - Return structured responses
+- Can be **regular tools** (organization-scoped) or **global tools** (platform-wide)
+
+#### Regular Tools (Default)
+
+Regular tools are scoped to specific organizations and validate that requests come from the same organization:
+
+- Validate OptiID organization ID matches the tool's organization
+- Only discoverable by `ToolFunction` instances
+- Default behavior when `isGlobal` is not specified or is `false`
+
+#### Global Tools
+
+Global tools work across all organizations without organization validation:
+
+- Accept OptiID authentication but don't validate organization ID
+- Only discoverable by `GlobalToolFunction` instances  
+- Must be explicitly marked with `isGlobal: true` in the `@tool` decorator
+- Useful for platform-wide utilities, shared services, or multi-tenant operations
 
 ### Interactions
 
@@ -175,7 +242,8 @@ The SDK automatically handles OptiID token validation for tool authorization. Op
 
 **Token Validation:**
 - The SDK extracts and validates OptiID tokens from the request body
-- Validation includes verifying that requests come from the same organization
+- **Regular Tools**: Validation includes verifying that requests come from the same organization as the tool
+- **Global Tools**: Token validation occurs but organization ID matching is skipped
 - If validation fails, returns HTTP 403 Unauthorized before reaching your handler methods
 - No additional configuration needed - validation is handled automatically
 
@@ -233,6 +301,7 @@ interface ToolConfig {
   parameters: ParameterConfig[];
   authRequirements?: AuthRequirementConfig[];
   endpoint: string;
+  isGlobal?: boolean;          // Optional: marks tool as global (default: false)
 }
 ```
 
@@ -251,7 +320,7 @@ interface InteractionConfig {
 
 #### `ToolFunction`
 
-Abstract base class for OCP functions:
+Abstract base class for organization-scoped OCP functions:
 
 ```typescript
 export abstract class ToolFunction extends Function {
@@ -260,7 +329,20 @@ export abstract class ToolFunction extends Function {
 }
 ```
 
-Extend this class and implement your OCP function. The `perform` method automatically routes requests to registered tools.
+Extend this class for regular tools that validate organization IDs. The `perform` method automatically routes requests to registered tools and enforces organization validation.
+
+#### `GlobalToolFunction`
+
+Abstract base class for global OCP functions:
+
+```typescript
+export abstract class GlobalToolFunction extends Function {
+  protected ready(): Promise<boolean>;
+  public async perform(): Promise<Response>;
+}
+```
+
+Extend this class for global tools that work across organizations. The `perform` method routes requests to registered tools but skips organization validation for global tools.
 
 ### Models
 
@@ -279,7 +361,14 @@ The SDK automatically provides two important endpoints:
 
 ### Discovery Endpoint (`/discovery`)
 
-Returns all registered tools in the proper OCP format for platform integration:
+Returns registered tools in the proper OCP format for platform integration. The discovery endpoint intelligently filters tools based on the function type:
+
+- **Regular Functions** (`ToolFunction`): Only returns non-global tools (organization-scoped)
+- **Global Functions** (`GlobalToolFunction`): Only returns global tools (marked with `isGlobal: true`)
+
+This ensures proper tool isolation and security boundaries between global and organization-specific tools.
+
+Example response for a regular and global function:
 
 ```json
 {
@@ -396,9 +485,9 @@ export class AuthenticatedFunction extends ToolFunction {
   async secureOperation(params: unknown, authData?: OptiIdAuthData) {
     if (!authData) throw new Error('OptiID authentication required');
     
-    const { customerId, accessToken } = authData.credentials;
+    const { customer_id, access_token } = authData.credentials;
     // Use OptiID credentials for API calls
-    return { success: true, customerId };
+    return { success: true, customer_id };
   }
 
   // Interaction with authentication example
@@ -411,11 +500,11 @@ export class AuthenticatedFunction extends ToolFunction {
       return new InteractionResult('Authentication required for webhook processing');
     }
 
-    const { customerId } = authData.credentials;
+    const { customer_id } = authData.credentials;
     
     // Process webhook data with authentication context
     return new InteractionResult(
-      `Webhook processed for customer ${customerId}: ${data.eventType}`,
+      `Webhook processed for customer ${customer_id}: ${data.eventType}`,
       `https://app.example.com/events/${data.eventId}`
     );
   }

package/dist/auth/AuthUtils.d.ts

@@ -1,31 +1,15 @@
-import { OptiIdAuthData } from '../types/Models';
 /**
- * Common authentication utilities for all function types
+ * Authorize a request for regular functions (with organization validation)
+ *
+ * @param request - The incoming request
+ * @returns true if authentication and authorization succeed
  */
-export declare class AuthUtils {
-    /**
-     * Validate the OptiID access token
-     *
-     * @param accessToken - The access token to validate
-     * @returns true if the token is valid
-     */
-    static validateAccessToken(accessToken: string | undefined): Promise<boolean>;
-    /**
-     * Extract and validate basic OptiID authentication data from request
-     *
-     * @param request - The incoming request
-     * @returns object with authData and accessToken, or null if invalid
-     */
-    static extractAuthData(request: any): {
-        authData: OptiIdAuthData;
-        accessToken: string;
-    } | null;
-    /**
-     * Validate organization ID matches the app context
-     *
-     * @param customerId - The customer ID from the auth data
-     * @returns true if the organization ID is valid
-     */
-    static validateOrganizationId(customerId: string | undefined): boolean;
-}
+export declare function authorizeRegularRequest(request: any): Promise<boolean>;
+/**
+ * Authorize a request for global functions (without organization validation)
+ *
+ * @param request - The incoming request
+ * @returns true if authentication succeeds
+ */
+export declare function authorizeGlobalRequest(request: any): Promise<boolean>;
 //# sourceMappingURL=AuthUtils.d.ts.map

package/dist/auth/AuthUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AuthUtils.d.ts","sourceRoot":"","sources":["../../src/auth/AuthUtils.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;GAEG;AACH,qBAAa,SAAS;IAEpB;;;;;OAKG;WACiB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC;IAa1F;;;;;OAKG;WACW,eAAe,CAAC,OAAO,EAAE,GAAG,GAAG;QAAE,QAAQ,EAAE,cAAc,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAWrG;;;;;OAKG;WACW,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO;CAc9E"}
+{"version":3,"file":"AuthUtils.d.ts","sourceRoot":"","sources":["../../src/auth/AuthUtils.ts"],"names":[],"mappings":"AAkGA;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,CAE5E;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,CAE3E"}

package/dist/auth/AuthUtils.js

@@ -1,64 +1,108 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AuthUtils = void 0;
+exports.authorizeRegularRequest = authorizeRegularRequest;
+exports.authorizeGlobalRequest = authorizeGlobalRequest;
 const app_sdk_1 = require("@zaiusinc/app-sdk");
 const TokenVerifier_1 = require("./TokenVerifier");
 /**
- * Common authentication utilities for all function types
+ * Validate the OptiID access token
+ *
+ * @param accessToken - The access token to validate
+ * @returns true if the token is valid
  */
-class AuthUtils {
-    /**
-     * Validate the OptiID access token
-     *
-     * @param accessToken - The access token to validate
-     * @returns true if the token is valid
-     */
-    static async validateAccessToken(accessToken) {
-        try {
-            if (!accessToken) {
-                return false;
-            }
-            const tokenVerifier = await (0, TokenVerifier_1.getTokenVerifier)();
-            return await tokenVerifier.verify(accessToken);
-        }
-        catch (error) {
-            app_sdk_1.logger.error('OptiID token validation failed:', error);
+async function validateAccessToken(accessToken) {
+    try {
+        if (!accessToken) {
             return false;
         }
+        const tokenVerifier = await (0, TokenVerifier_1.getTokenVerifier)();
+        return await tokenVerifier.verify(accessToken);
     }
-    /**
-     * Extract and validate basic OptiID authentication data from request
-     *
-     * @param request - The incoming request
-     * @returns object with authData and accessToken, or null if invalid
-     */
-    static extractAuthData(request) {
-        const authData = request?.bodyJSON?.auth;
-        const accessToken = authData?.credentials?.access_token;
-        if (!accessToken || authData?.provider?.toLowerCase() !== 'optiid') {
-            app_sdk_1.logger.error('OptiID token is required but not provided');
-            return null;
-        }
-        return { authData, accessToken };
+    catch (error) {
+        app_sdk_1.logger.error('OptiID token validation failed:', error);
+        return false;
     }
-    /**
-     * Validate organization ID matches the app context
-     *
-     * @param customerId - The customer ID from the auth data
-     * @returns true if the organization ID is valid
-     */
-    static validateOrganizationId(customerId) {
-        if (!customerId) {
-            app_sdk_1.logger.error('Organisation ID is required but not provided');
-            return false;
-        }
-        const appOrganisationId = (0, app_sdk_1.getAppContext)()?.account?.organizationId;
-        if (customerId !== appOrganisationId) {
-            app_sdk_1.logger.error(`Invalid organisation ID: expected ${appOrganisationId}, received ${customerId}`);
-            return false;
-        }
+}
+/**
+ * Extract and validate basic OptiID authentication data from request
+ *
+ * @param request - The incoming request
+ * @returns object with authData and accessToken, or null if invalid
+ */
+function extractAuthData(request) {
+    const authData = request?.bodyJSON?.auth;
+    const accessToken = authData?.credentials?.access_token;
+    if (!accessToken || authData?.provider?.toLowerCase() !== 'optiid') {
+        app_sdk_1.logger.error('OptiID token is required but not provided');
+        return null;
+    }
+    return { authData, accessToken };
+}
+/**
+ * Validate organization ID matches the app context
+ *
+ * @param customerId - The customer ID from the auth data
+ * @returns true if the organization ID is valid
+ */
+function validateOrganizationId(customerId) {
+    if (!customerId) {
+        app_sdk_1.logger.error('Organisation ID is required but not provided');
+        return false;
+    }
+    const appOrganisationId = (0, app_sdk_1.getAppContext)()?.account?.organizationId;
+    if (customerId !== appOrganisationId) {
+        app_sdk_1.logger.error(`Invalid organisation ID: expected ${appOrganisationId}, received ${customerId}`);
+        return false;
+    }
+    return true;
+}
+/**
+ * Check if a request should skip authentication (discovery/ready endpoints)
+ *
+ * @param request - The incoming request
+ * @returns true if auth should be skipped
+ */
+function shouldSkipAuth(request) {
+    return request.path === '/discovery' || request.path === '/ready';
+}
+/**
+ * Core authentication flow - extracts auth data and validates token
+ *
+ * @param request - The incoming request
+ * @param validateOrg - Whether to validate organization ID
+ * @returns true if authentication succeeds
+ */
+async function authenticateRequest(request, validateOrg = false) {
+    if (shouldSkipAuth(request)) {
         return true;
     }
+    const authInfo = extractAuthData(request);
+    if (!authInfo) {
+        return false;
+    }
+    const { authData, accessToken } = authInfo;
+    // Validate organization ID if required
+    if (validateOrg && !validateOrganizationId(authData.credentials?.customer_id)) {
+        return false;
+    }
+    return await validateAccessToken(accessToken);
+}
+/**
+ * Authorize a request for regular functions (with organization validation)
+ *
+ * @param request - The incoming request
+ * @returns true if authentication and authorization succeed
+ */
+async function authorizeRegularRequest(request) {
+    return await authenticateRequest(request, true);
+}
+/**
+ * Authorize a request for global functions (without organization validation)
+ *
+ * @param request - The incoming request
+ * @returns true if authentication succeeds
+ */
+async function authorizeGlobalRequest(request) {
+    return await authenticateRequest(request, false);
 }
-exports.AuthUtils = AuthUtils;
 //# sourceMappingURL=AuthUtils.js.map

package/dist/auth/AuthUtils.js.map

@@ -1 +1 @@
-{"version":3,"file":"AuthUtils.js","sourceRoot":"","sources":["../../src/auth/AuthUtils.ts"],"names":[],"mappings":";;;AAAA,+CAA0D;AAC1D,mDAAmD;AAGnD;;GAEG;AACH,MAAa,SAAS;IAEpB;;;;;OAKG;IACI,MAAM,CAAC,KAAK,CAAC,mBAAmB,CAAC,WAA+B;QACrE,IAAI,CAAC;YACH,IAAI,CAAC,WAAW,EAAE,CAAC;gBACjB,OAAO,KAAK,CAAC;YACf,CAAC;YACD,MAAM,aAAa,GAAG,MAAM,IAAA,gCAAgB,GAAE,CAAC;YAC/C,OAAO,MAAM,aAAa,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QACjD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,gBAAM,CAAC,KAAK,CAAC,iCAAiC,EAAE,KAAK,CAAC,CAAC;YACvD,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACI,MAAM,CAAC,eAAe,CAAC,OAAY;QACxC,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,EAAE,IAAsB,CAAC;QAC3D,MAAM,WAAW,GAAG,QAAQ,EAAE,WAAW,EAAE,YAAY,CAAC;QACxD,IAAI,CAAC,WAAW,IAAI,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,QAAQ,EAAE,CAAC;YACnE,gBAAM,CAAC,KAAK,CAAC,2CAA2C,CAAC,CAAC;YAC1D,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;IACnC,CAAC;IAED;;;;;OAKG;IACI,MAAM,CAAC,sBAAsB,CAAC,UAA8B;QACjE,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,gBAAM,CAAC,KAAK,CAAC,8CAA8C,CAAC,CAAC;YAC7D,OAAO,KAAK,CAAC;QACf,CAAC;QAED,MAAM,iBAAiB,GAAG,IAAA,uBAAa,GAAE,EAAE,OAAO,EAAE,cAAc,CAAC;QACnE,IAAI,UAAU,KAAK,iBAAiB,EAAE,CAAC;YACrC,gBAAM,CAAC,KAAK,CAAC,qCAAqC,iBAAiB,cAAc,UAAU,EAAE,CAAC,CAAC;YAC/F,OAAO,KAAK,CAAC;QACf,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AA1DD,8BA0DC"}
+{"version":3,"file":"AuthUtils.js","sourceRoot":"","sources":["../../src/auth/AuthUtils.ts"],"names":[],"mappings":";;AAwGA,0DAEC;AAQD,wDAEC;AApHD,+CAA0D;AAC1D,mDAAmD;AAGnD;;;;;GAKG;AACH,KAAK,UAAU,mBAAmB,CAAC,WAA+B;IAChE,IAAI,CAAC;QACH,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,OAAO,KAAK,CAAC;QACf,CAAC;QACD,MAAM,aAAa,GAAG,MAAM,IAAA,gCAAgB,GAAE,CAAC;QAC/C,OAAO,MAAM,aAAa,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IACjD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,gBAAM,CAAC,KAAK,CAAC,iCAAiC,EAAE,KAAK,CAAC,CAAC;QACvD,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAS,eAAe,CAAC,OAAY;IACnC,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,EAAE,IAAsB,CAAC;IAC3D,MAAM,WAAW,GAAG,QAAQ,EAAE,WAAW,EAAE,YAAY,CAAC;IACxD,IAAI,CAAC,WAAW,IAAI,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,QAAQ,EAAE,CAAC;QACnE,gBAAM,CAAC,KAAK,CAAC,2CAA2C,CAAC,CAAC;QAC1D,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;AACnC,CAAC;AAED;;;;;GAKG;AACH,SAAS,sBAAsB,CAAC,UAA8B;IAC5D,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,gBAAM,CAAC,KAAK,CAAC,8CAA8C,CAAC,CAAC;QAC7D,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,iBAAiB,GAAG,IAAA,uBAAa,GAAE,EAAE,OAAO,EAAE,cAAc,CAAC;IACnE,IAAI,UAAU,KAAK,iBAAiB,EAAE,CAAC;QACrC,gBAAM,CAAC,KAAK,CAAC,qCAAqC,iBAAiB,cAAc,UAAU,EAAE,CAAC,CAAC;QAC/F,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,SAAS,cAAc,CAAC,OAAY;IAClC,OAAO,OAAO,CAAC,IAAI,KAAK,YAAY,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ,CAAC;AACpE,CAAC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,mBAAmB,CAAC,OAAY,EAAE,cAAuB,KAAK;IAC3E,IAAI,cAAc,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,QAAQ,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IAC1C,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,GAAG,QAAQ,CAAC;IAE3C,uCAAuC;IACvC,IAAI,WAAW,IAAI,CAAC,sBAAsB,CAAC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,EAAE,CAAC;QAC9E,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,MAAM,mBAAmB,CAAC,WAAW,CAAC,CAAC;AAChD,CAAC;AAED;;;;;GAKG;AACI,KAAK,UAAU,uBAAuB,CAAC,OAAY;IACxD,OAAO,MAAM,mBAAmB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;AAClD,CAAC;AAED;;;;;GAKG;AACI,KAAK,UAAU,sBAAsB,CAAC,OAAY;IACvD,OAAO,MAAM,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;AACnD,CAAC"}