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

package/README.md

@@ -0,0 +1,631 @@
+# OPAL TOOL OCP SDK
+
+> **Optimizely Connect Platform (OCP) SDK for OPAL Tool**
+
+A TypeScript SDK for building Opal tools in Optimizely Connect Platform. This SDK provides decorators, abstractions, and utilities to simplify the development.
+
+## Features
+
+- 🎯 **Decorator-based Tool Registration** - Use `@tool` and `@interaction` decorators to easily register functions
+- 🔧 **Type-safe Development** - Full TypeScript support with comprehensive type definitions  
+- 🏗️ **Abstract Base Classes** - Extend `ToolFunction` for standardized request processing
+- 🔐 **Authentication Support** - OptiID authentication
+- 🛡️ **Authorization Support** - OptiID token tool authorization
+- 📝 **Parameter Validation** - Define and validate tool parameters with types
+- 🧪 **Comprehensive Testing** - Fully tested with Jest
+
+## Installation
+
+```bash
+npm install @optimizely-opal/opal-tool-ocp-sdk
+```
+
+or
+
+```bash
+yarn add @optimizely-opal/opal-tool-ocp-sdk
+```
+
+## Quick Start
+
+Create a tool function class by extending `ToolFunction` and registering your tools and interactions:
+
+```typescript
+import { ToolFunction, tool, interaction, ParameterType, InteractionResult, OptiIdAuthData } from '@optimizely-opal/opal-tool-ocp-sdk';
+
+export class MyToolFunction extends ToolFunction {
+
+  // Register a simple tool without authentication
+  @tool({
+    name: 'create_task',
+    description: 'Creates a new task in the system',
+    endpoint: '/create-task',
+    parameters: [
+      {
+        name: 'title',
+        type: ParameterType.String,
+        description: 'The task title',
+        required: true
+      },
+      {
+        name: 'priority',
+        type: ParameterType.String,
+        description: 'Task priority level',
+        required: false
+      }
+    ]
+  })
+  async createTask(params: { title: string; priority?: string }, authData?: OptiIdAuthData) {
+    return {
+      id: '123',
+      title: params.title,
+      priority: params.priority || 'medium'
+    };
+  }
+
+  // Register a tool with OptiID authentication
+  @tool({
+    name: 'secure_task',
+    description: 'Creates a secure task with OptiID authentication',
+    endpoint: '/secure-task',
+    parameters: [
+      {
+        name: 'title',
+        type: ParameterType.String,
+        description: 'The task title',
+        required: true
+      }
+    ],
+    authRequirements: [
+      {
+        provider: 'OptiID',
+        scopeBundle: 'tasks',
+        required: true
+      }
+    ]
+  })
+  async createSecureTask(params: { title: string }, authData?: OptiIdAuthData) {
+    if (!authData) {
+      throw new Error('OptiID authentication required');
+    }
+
+    const { customerId, instanceId, accessToken } = authData.credentials;
+    return {
+      id: '456',
+      title: params.title,
+      customerId,
+      instanceId
+    };
+  }
+
+  // Register an interaction
+  @interaction({
+    name: 'task_webhook',
+    endpoint: '/webhook/task'
+  })
+  async handleTaskWebhook(data: any): Promise<InteractionResult> {
+    return new InteractionResult(
+      `Task ${data.taskId} was updated`,
+      `https://app.example.com/tasks/${data.taskId}`
+    );
+  }
+}
+```
+
+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:
+
+- **Routes requests** to your registered tools and interactions based on endpoints
+- **Handles authentication** and OptiID token validation before calling your methods  
+- **Provides discovery** at `/discovery` endpoint for OCP platform integration
+- **Returns proper HTTP responses** with correct status codes and JSON formatting
+
+## Core Concepts
+
+### Tools
+
+Tools are functions that can be discovered and executed through the OCP platform. They:
+
+- Have a name, description, and endpoint
+- Define parameters with types and validation
+- Can require authentication
+- Return structured responses
+
+### Interactions
+
+Interactions are event handlers that process incoming data (like webhooks):
+
+- Have a name and endpoint
+- Process unstructured data
+- Return interaction results with messages and optional links
+
+### Parameters
+
+Supported parameter types:
+
+```typescript
+enum ParameterType {
+  String = 'string',
+  Integer = 'integer', 
+  Number = 'number',
+  Boolean = 'boolean',
+  List = 'list',
+  Dictionary = 'object'
+}
+```
+
+### Authentication
+
+The SDK supports authentication and authorization mechanisms:
+
+#### OptiID Authentication
+
+OptiID provides user authentication with type safety. This is the only user authentication provider currently supported in Opal:
+
+```typescript
+interface AuthRequirementConfig {
+  provider: string;        // 'OptiID'
+  scopeBundle: string;     // e.g., 'calendar', 'tasks'
+  required?: boolean;      // default: true
+}
+```
+
+#### OptiID Token Authorization
+
+The SDK automatically handles OptiID token validation for tool authorization. OptiID tokens provide both user authentication and authorization for tools, ensuring that only authenticated users with proper permissions can access your tools.
+
+**Token Validation:**
+- The SDK extracts and validates OptiID tokens from the request body
+- Validation includes verifying that requests come from the same organization
+- If validation fails, returns HTTP 403 Unauthorized before reaching your handler methods
+- No additional configuration needed - validation is handled automatically
+
+```typescript
+export class MyToolFunction extends ToolFunction {
+  @tool({
+    name: 'secure_tool',
+    description: 'Tool that validates requests from Opal',
+    endpoint: '/secure-endpoint',
+    parameters: [
+      { name: 'data', type: ParameterType.String, description: 'Data to process', required: true }
+    ]
+  })
+  async secureToolHandler(
+    params: { data: string }, 
+    authData?: OptiIdAuthData
+  ) {
+    
+    // Process the request knowing it's from a trusted Opal instance
+    return {
+      status: 'success',
+      data: `Processed: ${params.data}`,
+      authorizedBy: 'Opal'
+    };
+  }
+}
+```
+
+## API Reference
+
+### Handler Function Signatures
+
+All tool and interaction handler methods follow this signature pattern:
+
+```typescript
+async handlerMethod(
+  params: TParams,           // Tool parameters or interaction data
+  authData?: OptiIdAuthData  // OptiID user authentication data (if authenticated)
+): Promise<TResult>
+```
+
+- **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)`
+
+Registers a method as a discoverable tool.
+
+```typescript
+interface ToolConfig {
+  name: string;
+  description: string;
+  parameters: ParameterConfig[];
+  authRequirements?: AuthRequirementConfig[];
+  endpoint: string;
+}
+```
+
+#### `@interaction(config: InteractionConfig)`
+
+Registers a method as an interaction handler.
+
+```typescript
+interface InteractionConfig {
+  name: string;
+  endpoint: string;
+}
+```
+
+### Base Classes
+
+#### `ToolFunction`
+
+Abstract base class for OCP functions:
+
+```typescript
+export abstract class ToolFunction extends Function {
+  protected ready(): Promise<boolean>;
+  public async perform(): Promise<Response>;
+}
+```
+
+Extend this class and implement your OCP function. The `perform` method automatically routes requests to registered tools.
+
+### Models
+
+Key model classes with generic type support:
+
+- `Tool<TAuthData>` - Represents a registered tool with typed auth data
+- `Interaction<TAuthData>` - Represents an interaction handler with typed auth data
+- `Parameter` - Defines tool parameters
+- `AuthRequirement` - Defines authentication needs
+- `InteractionResult` - Response from interactions
+- `OptiIdAuthData` - OptiID specific authentication data
+
+## Discovery and Ready Endpoints
+
+The SDK automatically provides two important endpoints:
+
+### Discovery Endpoint (`/discovery`)
+
+Returns all registered tools in the proper OCP format for platform integration:
+
+```json
+{
+  "functions": [
+    {
+      "name": "create_task",
+      "description": "Creates a new task in the system",
+      "parameters": [
+        {
+          "name": "title",
+          "type": "string",
+          "description": "The task title",
+          "required": true
+        },
+        {
+          "name": "priority",
+          "type": "string",
+          "description": "Task priority level",
+          "required": false
+        }
+      ],
+      "endpoint": "/create-task",
+      "http_method": "POST"
+    },
+    {
+      "name": "secure_task",
+      "description": "Creates a secure task with OptiID authentication",
+      "parameters": [
+        {
+          "name": "title",
+          "type": "string",
+          "description": "The task title",
+          "required": true
+        }
+      ],
+      "endpoint": "/secure-task",
+      "http_method": "POST",
+      "auth_requirements": [
+        {
+          "provider": "OptiID",
+          "scope_bundle": "tasks",
+          "required": true
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Ready Endpoint (`/ready`)
+
+Returns the current readiness status of your function:
+
+```json
+{
+  "ready": true
+}
+```
+
+This endpoint calls your function's `ready()` method and returns:
+- `{ready: true}` when the function is ready to process requests
+- `{ready: false}` when the function is not ready (missing configuration, external services unavailable, etc.)
+- HTTP 200 status code regardless of ready state (the ready status is in the response body)
+
+## Development
+
+### Prerequisites
+
+- Node.js >= 22.0.0
+- TypeScript 5.x
+
+### Building
+
+```bash
+yarn build
+```
+
+### Testing
+
+```bash
+# Run tests
+yarn test
+
+# Run tests in watch mode
+yarn test:watch
+
+# Run tests with coverage
+yarn test:coverage
+```
+
+### Linting
+
+```bash
+yarn lint
+```
+
+## Examples
+
+### Function with Authentication
+
+```typescript
+import { ToolFunction, tool, interaction, ParameterType, OptiIdAuthData, InteractionResult } from '@optimizely-opal/opal-ocp-sdk';
+
+export class AuthenticatedFunction extends ToolFunction {
+
+  // OptiID authentication example
+  @tool({
+    name: 'secure_operation',
+    description: 'Performs a secure operation with OptiID',
+    endpoint: '/secure',
+    parameters: [],
+    authRequirements: [{ provider: 'OptiID', scopeBundle: 'tasks', required: true }]
+  })
+  async secureOperation(params: unknown, authData?: OptiIdAuthData) {
+    if (!authData) throw new Error('OptiID authentication required');
+    
+    const { customerId, accessToken } = authData.credentials;
+    // Use OptiID credentials for API calls
+    return { success: true, customerId };
+  }
+
+  // Interaction with authentication example
+  @interaction({
+    name: 'authenticated_webhook',
+    endpoint: '/secure-webhook'
+  })
+  async handleSecureWebhook(data: any, authData?: OptiIdAuthData): Promise<InteractionResult> {
+    if (!authData) {
+      return new InteractionResult('Authentication required for webhook processing');
+    }
+
+    const { customerId } = authData.credentials;
+    
+    // Process webhook data with authentication context
+    return new InteractionResult(
+      `Webhook processed for customer ${customerId}: ${data.eventType}`,
+      `https://app.example.com/events/${data.eventId}`
+    );
+  }
+}
+```
+
+### Organizing Tools in Separate Files
+
+For larger projects, you can organize your tools in separate files and import them into your main ToolFunction class:
+
+**Project Structure:**
+```
+src/
+├── tools/
+│   ├── index.ts
+│   ├── TaskTool.ts
+│   └── NotificationTool.ts
+└── MyToolFunction.ts
+```
+
+**tools/TaskTool.ts:**
+```typescript
+import { tool, ParameterType, OptiIdAuthData } from '@optimizely-opal/opal-ocp-sdk';
+
+export class TaskTool {
+  @tool({
+    name: 'create_task',
+    description: 'Creates a new task in the system',
+    endpoint: '/create-task',
+    parameters: [
+      {
+        name: 'title',
+        type: ParameterType.String,
+        description: 'The task title',
+        required: true
+      },
+      {
+        name: 'priority',
+        type: ParameterType.String,
+        description: 'Task priority level',
+        required: false
+      }
+    ]
+  })
+  async createTask(params: { title: string; priority?: string }, authData?: OptiIdAuthData) {
+    return {
+      id: '123',
+      title: params.title,
+      priority: params.priority || 'medium'
+    };
+  }
+
+  @tool({
+    name: 'delete_task',
+    description: 'Deletes a task from the system',
+    endpoint: '/delete-task',
+    parameters: [
+      {
+        name: 'taskId',
+        type: ParameterType.String,
+        description: 'The task ID to delete',
+        required: true
+      }
+    ]
+  })
+  async deleteTask(params: { taskId: string }, authData?: OptiIdAuthData) {
+    return { success: true, deletedTaskId: params.taskId };
+  }
+}
+```
+
+**tools/NotificationTool.ts:**
+```typescript
+import { tool, interaction, ParameterType, InteractionResult, OptiIdAuthData } from '@optimizely-opal/opal-ocp-sdk';
+
+export class NotificationTool {
+  @tool({
+    name: 'send_notification',
+    description: 'Sends a notification to users',
+    endpoint: '/send-notification',
+    parameters: [
+      {
+        name: 'message',
+        type: ParameterType.String,
+        description: 'The notification message',
+        required: true
+      },
+      {
+        name: 'userId',
+        type: ParameterType.String,
+        description: 'Target user ID',
+        required: true
+      }
+    ]
+  })
+  async sendNotification(params: { message: string; userId: string }, authData?: OptiIdAuthData) {
+    return {
+      notificationId: '456',
+      message: params.message,
+      userId: params.userId,
+      sent: true
+    };
+  }
+
+  @interaction({
+    name: 'notification_webhook',
+    endpoint: '/webhook/notification'
+  })
+  async handleNotificationWebhook(data: any): Promise<InteractionResult> {
+    return new InteractionResult(
+      `Notification ${data.notificationId} was delivered`,
+      `https://app.example.com/notifications/${data.notificationId}`
+    );
+  }
+}
+```
+
+**tools/index.ts:**
+```typescript
+export * from './TaskTool';
+export * from './NotificationTool';
+```
+
+**MyToolFunction.ts:**
+```typescript
+import { ToolFunction } from '@optimizely-opal/opal-ocp-sdk';
+import * from './tools';
+
+export class MyToolFunction extends ToolFunction {
+}
+```
+
+This approach provides several benefits:
+- **Better organization**: Each tool has its own file with related methods
+- **Maintainability**: Easier to find and modify specific tools
+- **Reusability**: Tools can be shared across different ToolFunction classes
+- **Team collaboration**: Different developers can work on different tool files
+- **Testing**: Each tool class can be unit tested independently
+
+## Decorator Behavior and Instance Context
+
+The `@tool` and `@interaction` decorators provide intelligent instance context management that behaves differently depending on where the decorated methods are defined:
+
+### ToolFunction Subclass Context
+
+When decorators are used in a class that extends `ToolFunction`, the decorators can reuse the existing ToolFunction instance when called through the `perform()` method:
+
+```typescript
+export class MyToolFunction extends ToolFunction {
+  private secretKey = process.env.SECRET_KEY;
+
+  @tool({
+    name: 'process_data',
+    description: 'Processes data using instance context',
+    endpoint: '/process-data',
+    parameters: [
+      { name: 'data', type: ParameterType.String, description: 'Data to process', required: true }
+    ]
+  })
+  async processData(params: { data: string }) {
+    // ✅ Can access instance properties and methods
+    // ✅ Can access this.request (inherited from ToolFunction)
+    // ✅ Shares state with other methods in the same request
+
+    const userAgent = this.request.headers.get('user-agent');
+    return {
+      processedData: this.encryptData(params.data),
+      userAgent,
+      timestamp: Date.now()
+    };
+  }
+
+  private encryptData(data: string): string {
+    // Uses instance property
+    return `encrypted_${data}_${this.secretKey}`;
+  }
+}
+```
+
+### Standalone Class Context
+
+When decorators are used in classes that don't extend `ToolFunction`, the decorators create new instances for each handler call:
+
+```typescript
+export class StandaloneToolService {
+  private config = { apiKey: 'standalone-key' };
+
+  @tool({
+    name: 'standalone_operation',
+    description: 'Standalone operation without ToolFunction',
+    endpoint: '/standalone',
+    parameters: [
+      { name: 'input', type: ParameterType.String, description: 'Input data', required: true }
+    ]
+  })
+  async standaloneOperation(params: { input: string }) {
+    // ✅ Can access instance properties and methods
+    // ❌ Cannot access this.request (not inherited from ToolFunction)
+    // ❌ No shared state with ToolFunction lifecycle
+
+    return {
+      result: `${this.helperMethod()}: ${params.input}`,
+      source: 'standalone'
+    };
+  }
+
+  private helperMethod() {
+    return this.config.apiKey;
+  }
+}
+```
+
+This behavior ensures that your tools can be both flexible (working in any class) and powerful (leveraging ToolFunction features when available).

package/dist/auth/AuthUtils.d.ts

@@ -0,0 +1,31 @@
+import { OptiIdAuthData } from '../types/Models';
+/**
+ * Common authentication utilities for all function types
+ */
+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;
+}
+//# 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;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"}