@optimizely-opal/opal-tool-ocp-sdk 0.0.0-devmg.12 → 1.0.0-beta.1

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 Function Modes** - SDK can be used in either global or organization-scoped mode
 - 🔧 **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 function modes:
+
+- **Regular Functions** (`ToolFunction`) - Organization-scoped functions that validate customer organization IDs
+- **Global Functions** (`GlobalToolFunction`) - Platform-wide functions that work across all organizations
+
+### Regular Tool Function
+
+Create a tool function class by extending `ToolFunction` for organization-scoped functionality:
 
 ```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,47 @@ 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 functionality:
+
+```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
+      }
+    ]
+  })
+  async globalUtility(params: { operation: string }, authData?: OptiIdAuthData) {
+    return {
+      result: `Performed ${params.operation} globally`,
+      organizationId: authData?.credentials.customer_id || 'unknown'
+    };
+  }
+}
+```
+
+### Function Modes
+
+The SDK operates in one of two modes based on the base class you extend:
+
+- **Regular Function Mode** (`ToolFunction`): All tools are organization-scoped and validate organization IDs
+- **Global Function Mode** (`GlobalToolFunction`): All tools are platform-wide.
+
+The discovery endpoint returns all tools registered within that function mode.
+
+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 +177,28 @@ 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
+- Are automatically registered based on the function mode you choose
+
+### Function Modes
+
+#### Regular Functions (`ToolFunction`)
+
+Regular functions are scoped to specific organizations and validate that requests come from the same organization:
+
+- Validate OptiID organization ID matches the function's organization context
+- All tools within the function are organization-scoped
+- **Per-Organization Configuration**: Can implement organization-specific configuration, authentication credentials, and API keys since they're tied to a single organization
+- **Per-Organization Authentication**: Can store and use organization-specific authentication tokens, connection strings, and other sensitive data securely
+
+#### Global Functions (`GlobalToolFunction`)
+
+Global functions work across all organizations without organization validation:
+
+- Accept OptiID authentication
+- All tools within the function are platform-wide
+- **No Per-Organization Configuration**: Cannot implement per-organization configuration since they work across all organizations
+- **No Per-Organization Authentication**: Cannot store organization-specific credentials or authentication data
+- **Global Discovery**: Have a global discovery URL that can be used by any organization without requiring them to install the app first
 
 ### Interactions
 
@@ -175,7 +245,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
 
@@ -220,6 +291,7 @@ async handlerMethod(
 - **params**: The input parameters for tools, or interaction data for webhooks
 - **authData**: Available when OptiID user authentication is configured and successful
 
+
 ### Decorators
 
 #### `@tool(config: ToolConfig)`
@@ -251,7 +323,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 +332,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 GlobalFunction {
+  protected ready(): Promise<boolean>;
+  public async perform(): Promise<Response>;
+}
+```
+
+Extend this class for tools that work across organizations. The `perform` method routes requests to registered tools but skips organization validation for tools.
 
 ### Models
 
@@ -279,7 +364,14 @@ The SDK automatically provides two important endpoints:
 
 ### Discovery Endpoint (`/discovery`)
 
-Returns all registered tools in the proper OCP format for platform integration:
+Returns all registered tools in the proper OCP format for platform integration. The discovery endpoint returns all tools registered within the function, regardless of their individual configuration:
+
+- **Regular Functions** (`ToolFunction`): Returns all tools with organization-scoped behavior
+- **Global Functions** (`GlobalToolFunction`): Returns all tools with platform-wide behavior
+
+All tools within a function operate in the same mode - there is no mixing of global and organization-scoped tools within a single function.
+
+Example response for a regular function and global function:
 
 ```json
 {
@@ -396,9 +488,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 +503,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}`
     );
   }
@@ -433,7 +525,8 @@ src/
 │   ├── index.ts
 │   ├── TaskTool.ts
 │   └── NotificationTool.ts
-└── MyToolFunction.ts
+├── MyToolFunction.ts
+└── MyGlobalToolFunction.ts
 ```
 
 **tools/TaskTool.ts:**

package/dist/auth/AuthUtils.d.ts

@@ -0,0 +1,26 @@
+import { OptiIdAuthData } from '../types/Models';
+/**
+ * Extract and validate basic OptiID authentication data from request
+ *
+ * @param request - The incoming request
+ * @returns object with authData and accessToken, or null if invalid
+ */
+export declare function extractAuthData(request: any): {
+    authData: OptiIdAuthData;
+    accessToken: string;
+} | null;
+/**
+ * Authenticate a request for regular functions (with organization validation)
+ *
+ * @param request - The incoming request
+ * @returns true if authentication and authorization succeed
+ */
+export declare function authenticateRegularRequest(request: any): Promise<boolean>;
+/**
+ * Authenticate a request for global functions (without organization validation)
+ *
+ * @param request - The incoming request
+ * @returns true if authentication succeeds
+ */
+export declare function authenticateGlobalRequest(request: any): Promise<boolean>;
+//# sourceMappingURL=AuthUtils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AuthUtils.d.ts","sourceRoot":"","sources":["../../src/auth/AuthUtils.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAqBjD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,GAAG,GAAG;IAAE,QAAQ,EAAE,cAAc,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAQtG;AA6DD;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,CAE/E;AAED;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,CAE9E"}

package/dist/auth/AuthUtils.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractAuthData = extractAuthData;
+exports.authenticateRegularRequest = authenticateRegularRequest;
+exports.authenticateGlobalRequest = authenticateGlobalRequest;
+const app_sdk_1 = require("@zaiusinc/app-sdk");
+const TokenVerifier_1 = require("./TokenVerifier");
+/**
+ * Validate the OptiID access token
+ *
+ * @param accessToken - The access token to validate
+ * @returns true if the token is valid
+ */
+async function 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);
+        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') {
+        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) {
+    if (shouldSkipAuth(request)) {
+        return true;
+    }
+    const authInfo = extractAuthData(request);
+    if (!authInfo) {
+        app_sdk_1.logger.error('OptiID token is required but not provided');
+        return false;
+    }
+    const { authData, accessToken } = authInfo;
+    // Validate organization ID if required
+    if (validateOrg && !validateOrganizationId(authData.credentials?.customer_id)) {
+        return false;
+    }
+    return await validateAccessToken(accessToken);
+}
+/**
+ * Authenticate a request for regular functions (with organization validation)
+ *
+ * @param request - The incoming request
+ * @returns true if authentication and authorization succeed
+ */
+async function authenticateRegularRequest(request) {
+    return await authenticateRequest(request, true);
+}
+/**
+ * Authenticate a request for global functions (without organization validation)
+ *
+ * @param request - The incoming request
+ * @returns true if authentication succeeds
+ */
+async function authenticateGlobalRequest(request) {
+    return await authenticateRequest(request, false);
+}
+//# sourceMappingURL=AuthUtils.js.map

package/dist/auth/AuthUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AuthUtils.js","sourceRoot":"","sources":["../../src/auth/AuthUtils.ts"],"names":[],"mappings":";;AA6BA,0CAQC;AAmED,gEAEC;AAQD,8DAEC;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,SAAgB,eAAe,CAAC,OAAY;IAC1C,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,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,WAAoB;IACnE,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,gBAAM,CAAC,KAAK,CAAC,2CAA2C,CAAC,CAAC;QAC1D,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,0BAA0B,CAAC,OAAY;IAC3D,OAAO,MAAM,mBAAmB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;AAClD,CAAC;AAED;;;;;GAKG;AACI,KAAK,UAAU,yBAAyB,CAAC,OAAY;IAC1D,OAAO,MAAM,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;AACnD,CAAC"}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=AuthUtils.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AuthUtils.test.d.ts","sourceRoot":"","sources":["../../src/auth/AuthUtils.test.ts"],"names":[],"mappings":""}