@optimizely-opal/opal-tool-ocp-sdk 0.0.0-beta.1

package/README.md

@@ -0,0 +1,576 @@
+# 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** - Bearer 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 {
+  // Implement required bearer token validation method
+  validateBearerToken(token: string): boolean {
+    const expectedToken = process.env.OPAL_TOOL_TOKEN;
+    return token === expectedToken;
+  }
+
+  // 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 bearer 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
+}
+```
+
+#### Bearer Token Support
+
+The SDK automatically extracts Bearer tokens from the `authorization` header for tool authorization. When users register tools in Opal, they can specify a Bearer token that Opal will include in requests to validate the tool's identity.
+
+**Token Validation:**
+- Bearer tokens are extracted from the `authorization: Bearer <token>` header
+- Empty strings and `undefined` tokens are treated as missing (no validation performed)
+- Implement the abstract `validateBearerToken(token: string): boolean` method to define your validation logic
+
+```typescript
+export class MyToolFunction extends ToolFunction {
+  // Implement the required bearer token validation method
+  validateBearerToken(token: string): boolean {
+    // If you don't need bearer token validation, simply return true
+    // return true;
+    
+    // For actual validation, compare against expected token
+    const expectedToken = process.env.OPAL_TOOL_TOKEN;
+    return token === expectedToken;
+  }
+
+  @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'
+    };
+  }
+}
+```
+
+**Bearer Token Usage:**
+- Set by users when registering tools in Opal
+- Used to authorize tool requests from Opal instances  
+- Validates that requests are coming from trusted Opal sources
+- Requires implementing the abstract `validateBearerToken(token: string): boolean` method
+- If validation fails, returns HTTP 403 Forbidden before reaching your handler methods
+
+
+## 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
+
+**Note**: Bearer token validation is handled automatically by the base class. If a bearer token is present and fails validation, the request is rejected before reaching your handler methods.
+
+### 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 {
+  public async perform(): Promise<Response>;
+  protected abstract validateBearerToken(token: string): boolean;
+}
+```
+
+Extend this class and implement your OCP function. The `perform` method automatically routes requests to registered tools and handles bearer token validation. You must implement the `validateBearerToken` method to define how bearer tokens should be validated for your 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 Endpoint
+
+The SDK automatically provides a discovery endpoint at `/discovery` that returns all registered tools in the proper OCP format:
+
+```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
+        }
+      ]
+    }
+  ]
+}
+```
+
+## 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 {
+  // Implement required bearer token validation
+  validateBearerToken(token: string): boolean {
+    // If you don't need bearer token validation, simply return true
+    // return true;
+    
+    // For actual validation, compare against expected token
+    const expectedToken = process.env.OPAL_TOOL_TOKEN;
+    return token === expectedToken;
+  }
+
+  // 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 {
+
+  // Implement required bearer token validation method
+  validateBearerToken(token: string): boolean {
+    const expectedToken = process.env.OPAL_TOOL_TOKEN;
+    return token === expectedToken;
+  }
+}
+```
+
+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

package/dist/decorator/Decorator.d.ts

@@ -0,0 +1,46 @@
+import { ParameterType } from '../types/Models';
+/**
+ * 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
+ */
+export declare function tool(config: ToolConfig): (_target: any, _propertyKey: string, descriptor: PropertyDescriptor) => void;
+/**
+ * Decorator for registering interaction functions
+ * Immediately registers the interaction with the global ToolsService
+ */
+export declare function interaction(config: InteractionConfig): (_target: any, _propertyKey: string, descriptor: PropertyDescriptor) => void;
+//# sourceMappingURL=Decorator.d.ts.map

package/dist/decorator/Decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Decorator.d.ts","sourceRoot":"","sources":["../../src/decorator/Decorator.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8B,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAG5E;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,gBAAgB,CAAC,EAAE,qBAAqB,EAAE,CAAC;IAC3C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,aAAa,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAgB,IAAI,CAAC,MAAM,EAAE,UAAU,IACrB,SAAS,GAAG,EAAE,cAAc,MAAM,EAAE,YAAY,kBAAkB,UAqBnF;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,iBAAiB,IACnC,SAAS,GAAG,EAAE,cAAc,MAAM,EAAE,YAAY,kBAAkB,UAQnF"}

package/dist/decorator/Decorator.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tool = tool;
+exports.interaction = interaction;
+const Models_1 = require("../types/Models");
+const Service_1 = require("../service/Service");
+/**
+ * Decorator for registering tool functions
+ * Immediately registers the tool with the global ToolsService
+ */
+function tool(config) {
+    return function (_target, _propertyKey, descriptor) {
+        // Convert parameter configs to Parameter instances
+        const parameters = (config.parameters || []).map((p) => new Models_1.Parameter(p.name, p.type, p.description, p.required));
+        // Convert auth requirement configs to AuthRequirement instances
+        const authRequirements = (config.authRequirements || []).map((a) => new Models_1.AuthRequirement(a.provider, a.scopeBundle, a.required));
+        // Immediately register with global ToolsService
+        Service_1.toolsService.registerTool(config.name, config.description, descriptor.value, parameters, config.endpoint, authRequirements);
+    };
+}
+/**
+ * Decorator for registering interaction functions
+ * Immediately registers the interaction with the global ToolsService
+ */
+function interaction(config) {
+    return function (_target, _propertyKey, descriptor) {
+        // Immediately register with global ToolsService
+        Service_1.toolsService.registerInteraction(config.name, descriptor.value, config.endpoint);
+    };
+}
+//# sourceMappingURL=Decorator.js.map

package/dist/decorator/Decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Decorator.js","sourceRoot":"","sources":["../../src/decorator/Decorator.ts"],"names":[],"mappings":";;AA6CA,oBAsBC;AAMD,kCASC;AAlFD,4CAA4E;AAC5E,gDAAkD;AAwClD;;;GAGG;AACH,SAAgB,IAAI,CAAC,MAAkB;IACrC,OAAO,UAAS,OAAY,EAAE,YAAoB,EAAE,UAA8B;QAChF,mDAAmD;QACnD,MAAM,UAAU,GAAG,CAAC,MAAM,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CACrD,IAAI,kBAAS,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,QAAQ,CAAC,CACzD,CAAC;QAEF,gEAAgE;QAChE,MAAM,gBAAgB,GAAG,CAAC,MAAM,CAAC,gBAAgB,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CACjE,IAAI,wBAAe,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,QAAQ,CAAC,CAC3D,CAAC;QAEF,gDAAgD;QAChD,sBAAY,CAAC,YAAY,CACvB,MAAM,CAAC,IAAI,EACX,MAAM,CAAC,WAAW,EAClB,UAAU,CAAC,KAAK,EAChB,UAAU,EACV,MAAM,CAAC,QAAQ,EACf,gBAAgB,CACjB,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAgB,WAAW,CAAC,MAAyB;IACnD,OAAO,UAAS,OAAY,EAAE,YAAoB,EAAE,UAA8B;QAChF,gDAAgD;QAChD,sBAAY,CAAC,mBAAmB,CAC9B,MAAM,CAAC,IAAI,EACX,UAAU,CAAC,KAAK,EAChB,MAAM,CAAC,QAAQ,CAChB,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}

package/dist/decorator/Decorator.test.d.ts

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

package/dist/decorator/Decorator.test.d.ts.map

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