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

package/src/service/Service.ts

@@ -0,0 +1,213 @@
+/* eslint-disable max-classes-per-file */
+import { AuthRequirement, Parameter } from '../types/Models';
+import * as App from '@zaiusinc/app-sdk';
+import { logger } from '@zaiusinc/app-sdk';
+import { ToolFunction } from '../function/ToolFunction';
+import { GlobalToolFunction } from '../function/GlobalToolFunction';
+
+/**
+ * Default OptiID authentication requirement that will be enforced for all tools
+ */
+const DEFAULT_OPTIID_AUTH = new AuthRequirement('OptiID', 'default', true);
+
+
+
+/**
+ * Result type for interaction handlers
+ */
+export class InteractionResult {
+  public constructor(
+    public message: string,
+    public link?: string
+  ) {}
+}
+
+/**
+ * Interaction definition for an Opal interaction
+ */
+export class Interaction<TAuthData> {
+  public constructor(
+    public name: string,
+    public endpoint: string,
+    public handler: (
+      functionContext: ToolFunction | GlobalToolFunction,
+      data: unknown,
+      authData?: TAuthData
+    ) => Promise<InteractionResult>
+  ) {}
+}
+
+/**
+ * Tool definition for an Opal tool
+ */
+export class Tool<TAuthData> {
+  /**
+   * HTTP method for the endpoint (default: POST)
+   */
+  public httpMethod: string = 'POST';
+
+  /**
+   * Create a new function definition
+   * @param name Function name
+   * @param description Function description
+   * @param parameters Function parameters
+   * @param endpoint API endpoint
+   * @param handler Function implementing the tool
+   * @param authRequirements Authentication requirements (mandatory - OptiID enforced)
+   */
+  public constructor(
+    public name: string,
+    public description: string,
+    public parameters: Parameter[],
+    public endpoint: string,
+    public handler: (
+      functionContext: ToolFunction | GlobalToolFunction,
+      params: unknown,
+      authData?: TAuthData
+    ) => Promise<unknown>,
+    public authRequirements: AuthRequirement[] = [DEFAULT_OPTIID_AUTH]
+  ) {}
+
+  /**
+   * Convert to JSON for the discovery endpoint
+   */
+  public toJSON(): Record<string, unknown> {
+    const result: Record<string, unknown> = {
+      name: this.name,
+      description: this.description,
+      parameters: this.parameters.map((p) => p.toJSON()),
+      endpoint: this.endpoint,
+      http_method: this.httpMethod,
+      auth_requirements: this.authRequirements.map((auth) => auth.toJSON())
+    };
+
+    return result;
+  }
+}
+
+export class ToolsService {
+  private functions: Map<string, Tool<any>> = new Map();
+  private interactions: Map<string, Interaction<any>> = new Map();
+
+  /**
+   * Enforce OptiID authentication for tools by ensuring OptiID auth requirement is present
+   * @param authRequirements Original authentication requirements
+   * @returns Enforced authentication requirements with OptiID
+   */
+  private enforceOptiIdAuth(authRequirements?: AuthRequirement[]): AuthRequirement[] {
+    const hasOptiIdProvider = authRequirements
+      && authRequirements.some((auth) => auth.provider.toLowerCase() === 'optiid');
+
+    if (hasOptiIdProvider) {
+      return authRequirements;
+    }
+
+    return [...(authRequirements || []), DEFAULT_OPTIID_AUTH];
+  }
+
+  /**
+   * Register a tool function with generic auth data
+   * @param name Tool name
+   * @param description Tool description
+   * @param handler Function implementing the tool
+   * @param parameters List of parameters for the tool
+   * @param endpoint API endpoint for the tool
+   * @param authRequirements Authentication requirements (optional)
+   */
+  public registerTool<TAuthData>(
+    name: string,
+    description: string,
+    handler: (
+      functionContext: ToolFunction | GlobalToolFunction,
+      params: unknown,
+      authData?: TAuthData
+    ) => Promise<unknown>,
+    parameters: Parameter[],
+    endpoint: string,
+    authRequirements?: AuthRequirement[]
+  ): void {
+    // Enforce OptiID authentication for all tools
+    const enforcedAuthRequirements = this.enforceOptiIdAuth(authRequirements);
+    const func = new Tool<TAuthData>(
+      name,
+      description,
+      parameters,
+      endpoint,
+      handler,
+      enforcedAuthRequirements
+    );
+    this.functions.set(endpoint, func);
+  }
+
+  /**
+   * Register a tool interaction with generic auth data
+   * @param name Tool name
+   * @param handler Function implementing the tool
+   * @param endpoint API endpoint for the tool
+   */
+  public registerInteraction<TAuthData>(
+    name: string,
+    handler: (
+      functionContext: ToolFunction | GlobalToolFunction,
+      data: unknown,
+      authData?: TAuthData
+    ) => Promise<InteractionResult>,
+    endpoint: string
+  ): void {
+    const func = new Interaction<TAuthData>(name, endpoint, handler);
+    this.interactions.set(endpoint, func);
+  }
+
+  public async processRequest(req: App.Request,
+                              functionContext: ToolFunction | GlobalToolFunction): Promise<App.Response> {
+    if (req.path === '/discovery') {
+      return new App.Response(200, { functions: Array.from(this.functions.values()).map((f) => f.toJSON()) });
+    } else {
+      const func = this.functions.get(req.path);
+      if (func) {
+        try {
+          let params;
+          if (req.bodyJSON && req.bodyJSON.parameters) {
+            params = req.bodyJSON.parameters;
+          } else {
+            params = req.bodyJSON;
+          }
+
+          // Extract auth data from body JSON
+          const authData = req.bodyJSON ? req.bodyJSON.auth : undefined;
+
+          const result = await func.handler(functionContext, params, authData);
+          return new App.Response(200, result);
+        } catch (error: any) {
+          logger.error(`Error in function ${func.name}:`, error);
+          return new App.Response(500, { error: error.message || 'Unknown error' });
+        }
+      }
+
+      const interaction = this.interactions.get(req.path);
+      if (interaction) {
+        try {
+          let params;
+          if (req.bodyJSON && req.bodyJSON.data) {
+            params = req.bodyJSON.data;
+          } else {
+            params = req.bodyJSON;
+          }
+
+          // Extract auth data from body JSON
+          const authData = req.bodyJSON ? req.bodyJSON.auth : undefined;
+
+          const result = await interaction.handler(functionContext, params, authData);
+          return new App.Response(200, result);
+        } catch (error: any) {
+          logger.error(`Error in function ${interaction.name}:`, error);
+          return new App.Response(500, { error: error.message || 'Unknown error' });
+        }
+      }
+
+      return new App.Response(404, 'Function not found');
+    }
+  }
+}
+
+export const toolsService = new ToolsService();

package/src/types/Models.ts

@@ -0,0 +1,163 @@
+/* eslint-disable max-classes-per-file */
+/**
+ * Types of parameters supported by Opal tools
+ */
+export enum ParameterType {
+  String = 'string',
+  Integer = 'integer',
+  Number = 'number',
+  Boolean = 'boolean',
+  List = 'list',
+  Dictionary = 'object'
+}
+
+/**
+ * Parameter definition for an Opal tool
+ */
+export class Parameter {
+  /**
+   * Create a new parameter definition
+   * @param name Parameter name
+   * @param type Parameter type
+   * @param description Parameter description
+   * @param required Whether the parameter is required
+   */
+  public constructor(
+    public name: string,
+    public type: ParameterType,
+    public description: string,
+    public required: boolean
+  ) {}
+
+  /**
+   * Convert to JSON for the discovery endpoint
+   */
+  public toJSON() {
+    return {
+      name: this.name,
+      type: this.type,
+      description: this.description,
+      required: this.required
+    };
+  }
+}
+
+/**
+ * Credentials structure
+ */
+export class OptiIdAuthDataCredentials {
+
+  public constructor(
+    public customer_id: string,
+    public instance_id: string,
+    public access_token: string,
+    public product_sku: string
+  ) {}
+}
+
+
+/**
+ * Auth data structure
+ */
+export class OptiIdAuthData {
+
+  public constructor(
+    public provider: string,
+    public credentials: OptiIdAuthDataCredentials
+  ) {}
+}
+
+/**
+ * Authentication requirements for an Opal tool
+ */
+export class AuthRequirement {
+  /**
+   * Create a new authentication requirement
+   * @param provider Auth provider (e.g., "optiId")
+   * @param scopeBundle Scope bundle (e.g., "calendar", "drive")
+   * @param required Whether authentication is required
+   */
+  public constructor(
+    public provider: string,
+    public scopeBundle: string,
+    public required: boolean = true
+  ) {}
+
+  /**
+   * Convert to JSON for the discovery endpoint
+   */
+  public toJSON() {
+    return {
+      provider: this.provider,
+      scope_bundle: this.scopeBundle,
+      required: this.required
+    };
+  }
+}
+
+export class IslandField {
+
+  public constructor(
+    public name: string,
+    public label: string,
+    public type: 'string' | 'boolean' | 'json',
+    public value: string | boolean | object = '',
+    public hidden: boolean = false,
+    public options: string[] = []
+  ) {}
+
+  public toJSON() {
+    return {
+      name: this.name,
+      label: this.label,
+      type: this.type,
+      hidden: this.hidden,
+      options: this.options,
+      value: this.value
+    };
+  }
+}
+
+export class IslandAction {
+
+  public constructor(
+    public name: string,
+    public label: string,
+    public type: string,
+    public endpoint: string,
+    public operation: string = 'create'
+  ) {}
+
+  public toJSON() {
+    return {
+      name: this.name,
+      label: this.label,
+      type: this.type,
+      endpoint: this.endpoint,
+      operation: this.operation
+    };
+  }
+}
+
+export class IslandConfig {
+
+  public constructor(
+    public fields: IslandField[],
+    public actions: IslandAction[]
+  ) {}
+}
+
+export class IslandResponse {
+
+  public constructor(
+    public type: 'island',
+    public config: {
+      islands: IslandConfig[];
+    }
+  ) {}
+
+  public static create(islands: IslandConfig[]): IslandResponse {
+    return new IslandResponse('island', { islands });
+  }
+}
+