@optimizely-opal/opal-tool-ocp-sdk 1.0.0 → 1.1.0-beta.2

package/src/service/Service.ts

@@ -1,14 +1,14 @@
 /* eslint-disable max-classes-per-file */
-import { AuthRequirement, IslandResponse, Parameter } from '../types/Models';
+import { AuthRequirement, IslandResponse, OAuthAuthData, OptiIdAuthData, Parameter } from '../types/Models';
 import { ToolError } from '../types/ToolError';
 import * as App from '@zaiusinc/app-sdk';
-import { logger, Headers, getAppContext } from '@zaiusinc/app-sdk';
+import { logger, getAppContext } from '@zaiusinc/app-sdk';
 import { ToolFunction } from '../function/ToolFunction';
 import { GlobalToolFunction } from '../function/GlobalToolFunction';
 import { ParameterValidator } from '../validation/ParameterValidator';
 
 /**
- * Default OptiID authentication requirement that will be enforced for all tools
+ * Default OptiID authentication requirement added when tool doesn't specify any auth
  */
 const DEFAULT_OPTIID_AUTH = new AuthRequirement('OptiID', 'default', true);
 
@@ -53,14 +53,14 @@ export class InteractionResult {
 /**
  * Interaction definition for an Opal interaction
  */
-export class Interaction<TAuthData> {
+export class Interaction {
   public constructor(
     public name: string,
     public endpoint: string,
     public handler: (
       functionContext: ToolFunction | GlobalToolFunction,
       data: unknown,
-      authData?: TAuthData
+      authData: OptiIdAuthData | OAuthAuthData
     ) => Promise<InteractionResult>
   ) {}
 }
@@ -68,7 +68,7 @@ export class Interaction<TAuthData> {
 /**
  * Tool definition for an Opal tool
  */
-export class Tool<TAuthData> {
+export class Tool {
   /**
    * HTTP method for the endpoint (default: POST)
    */
@@ -91,7 +91,7 @@ export class Tool<TAuthData> {
     public handler: (
       functionContext: ToolFunction | GlobalToolFunction,
       params: unknown,
-      authData?: TAuthData
+      authData: OptiIdAuthData | OAuthAuthData
     ) => Promise<unknown>,
     public authRequirements: AuthRequirement[] = [DEFAULT_OPTIID_AUTH]
   ) {}
@@ -114,8 +114,8 @@ export class Tool<TAuthData> {
 }
 
 export class ToolsService {
-  private functions: Map<string, Tool<any>> = new Map();
-  private interactions: Map<string, Interaction<any>> = new Map();
+  private functions: Map<string, Tool> = new Map();
+  private interactions: Map<string, Interaction> = new Map();
 
   /**
    * Generate KV store key for tool overrides
@@ -144,7 +144,7 @@ export class ToolsService {
    * @param overrides Override data
    * @returns Tools with overrides applied
    */
-  private applyOverrides(tools: Array<Tool<any>>, overrides: StoredOverrides): Array<Tool<any>> {
+  private applyOverrides(tools: Tool[], overrides: StoredOverrides): Tool[] {
     return tools.map((tool) => {
       const override = overrides[tool.name];
       if (!override) {
@@ -207,7 +207,7 @@ export class ToolsService {
    * @param functionName Function name
    * @returns Tool definitions with overrides applied
    */
-  public async getToolsWithOverrides(appVersionId: string, functionName: string): Promise<Array<Tool<any>>> {
+  public async getToolsWithOverrides(appVersionId: string, functionName: string): Promise<Tool[]> {
     const tools = Array.from(this.functions.values());
     const overrides = await this.getOverrides(appVersionId, functionName);
 
@@ -219,50 +219,35 @@ export class ToolsService {
   }
 
   /**
-   * Enforce OptiID authentication for tools by ensuring OptiID auth requirement is present
+   * Apply default auth requirements if none are specified
    * @param authRequirements Original authentication requirements
-   * @returns Enforced authentication requirements with OptiID
+   * @returns Auth requirements with default OptiID if none specified, otherwise unchanged
    */
-  private enforceOptiIdAuth(authRequirements?: AuthRequirement[]): AuthRequirement[] {
-    const hasOptiIdProvider = authRequirements
-      && authRequirements.some((auth) => auth.provider.toLowerCase() === 'optiid');
-
-    if (hasOptiIdProvider) {
-      return authRequirements;
+  private withDefaultAuthRequirements(authRequirements?: AuthRequirement[]): AuthRequirement[] {
+    // Only add default OptiID if no auth requirements are specified
+    if (!authRequirements || authRequirements.length === 0) {
+      return [DEFAULT_OPTIID_AUTH];
     }
 
-    return [...(authRequirements || []), DEFAULT_OPTIID_AUTH];
+    // Respect developer's choice - return as-is
+    return authRequirements;
   }
 
   /**
-   * Format an error as RFC 9457 Problem Details response
-   * @param error The error to format
-   * @param instance URI reference identifying the specific occurrence
-   * @returns RFC 9457 compliant Response
+   * Check if an endpoint requires OptiID authentication
+   * Tools: Check auth requirements for OptiID provider
+   * Interactions: Always require OptiID
+   * @param endpoint The endpoint path to check
+   * @returns true if the endpoint requires OptiID auth
    */
-  private formatErrorResponse(error: any, instance: string): App.Response {
-    let status = 500;
-    let problemDetails: Record<string, unknown>;
-
-    if (error instanceof ToolError) {
-      // Use ToolError's status and format
-      status = error.status;
-      problemDetails = error.toProblemDetails(instance);
-    } else {
-      // Convert regular errors to RFC 9457 format with 500 status
-      problemDetails = {
-        title: 'Internal Server Error',
-        status: 500,
-        detail: error.message || 'An unexpected error occurred',
-        instance
-      };
+  public requiresOptiIdAuth(endpoint: string): boolean {
+    const func = this.functions.get(endpoint);
+    if (func) {
+      return func.authRequirements.some((auth) => auth.provider.toLowerCase() === 'optiid');
     }
-
-    return new App.Response(
-      status,
-      problemDetails,
-      new Headers([['content-type', 'application/problem+json']])
-    );
+    // Interactions always require OptiID
+    const interaction = this.interactions.get(endpoint);
+    return !!interaction;
   }
 
   /**
@@ -272,29 +257,28 @@ export class ToolsService {
    * @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)
+   * @param authRequirements Authentication requirements (optional - defaults to OptiID if not specified)
    */
-  public registerTool<TAuthData>(
+  public registerTool(
     name: string,
     description: string,
     handler: (
       functionContext: ToolFunction | GlobalToolFunction,
       params: unknown,
-      authData?: TAuthData
+      authData: OptiIdAuthData | OAuthAuthData
     ) => 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>(
+    const resolvedAuthRequirements = this.withDefaultAuthRequirements(authRequirements);
+    const func = new Tool(
       name,
       description,
       parameters,
       endpoint,
       handler,
-      enforcedAuthRequirements
+      resolvedAuthRequirements
     );
     this.functions.set(endpoint, func);
   }
@@ -305,16 +289,16 @@ export class ToolsService {
    * @param handler Function implementing the tool
    * @param endpoint API endpoint for the tool
    */
-  public registerInteraction<TAuthData>(
+  public registerInteraction(
     name: string,
     handler: (
       functionContext: ToolFunction | GlobalToolFunction,
       data: unknown,
-      authData?: TAuthData
+      authData: OptiIdAuthData | OAuthAuthData
     ) => Promise<InteractionResult>,
     endpoint: string
   ): void {
-    const func = new Interaction<TAuthData>(name, endpoint, handler);
+    const func = new Interaction(name, endpoint, handler);
     this.interactions.set(endpoint, func);
   }
 
@@ -327,61 +311,53 @@ export class ToolsService {
       return await this.handleDiscoveryRequest(functionContext);
     }
 
-    // Handle overrides endpoint
+    // Handle overrides endpoint (auth handled by function layer)
     if (req.path === '/overrides') {
       return await this.handleOverridesRequest(req, functionContext);
     }
 
     // Handle regular tool functions
+    // Auth is already validated by the function layer
     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;
-        }
+      const params = req.bodyJSON?.parameters ?? req.bodyJSON;
 
-        // Validate parameters before calling the handler (only if tool has parameter definitions)
-        // ParameterValidator.validate() throws ToolError if validation fails
-        if (func.parameters && func.parameters.length > 0) {
-          ParameterValidator.validate(params, func.parameters, func.endpoint);
-        }
+      // Validate parameters before calling the handler (only if tool has parameter definitions)
+      // ParameterValidator.validate() throws ToolError if validation fails
+      if (func.parameters && func.parameters.length > 0) {
+        ParameterValidator.validate(params, func.parameters, func.endpoint);
+      }
 
-        // 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 this.formatErrorResponse(error, func.endpoint);
+      // Extract auth data from body JSON
+      const authData = req.bodyJSON?.auth;
+
+      // Validate auth data is present if tool has auth requirements
+      if (func.authRequirements.length > 0 && !authData) {
+        throw new ToolError('Authentication data is required', 403);
       }
+
+      const result = await func.handler(functionContext, params, authData);
+      return new App.Response(200, result);
     }
 
     // Handle interactions
     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;
-        }
+      const params = req.bodyJSON?.data ?? 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 this.formatErrorResponse(error, interaction.endpoint);
+      // Extract auth data from body JSON
+      const authData = req.bodyJSON?.auth;
 
+      // Interactions always require auth
+      if (!authData) {
+        throw new ToolError('Authentication data is required', 403);
       }
+
+      const result = await interaction.handler(functionContext, params, authData);
+      return new App.Response(200, result);
     }
-    return new App.Response(404, 'Function not found');
+
+    throw new ToolError('Function not found', 404);
   }
 
   /**

package/src/types/Models.ts

@@ -43,29 +43,38 @@ export class Parameter {
 }
 
 /**
- * Credentials structure
+ * Credentials structure ofr OptiID provider
  */
-export class OptiIdAuthDataCredentials {
+export interface OptiIdAuthDataCredentials {
+  customer_id: string;
+  instance_id: string;
+  access_token: string;
+  product_sku: string;
+}
 
-  public constructor(
-    public customer_id: string,
-    public instance_id: string,
-    public access_token: string,
-    public product_sku: string
-  ) {}
+/**
+ * Credentials structure for OAuth providers
+ */
+export interface OAuthProviderAuthDataCredentials {
+  access_token: string;
+ token_type: string;
+ expires_at: string;
 }
 
+export interface OptiIdAuthData {
+  provider: 'OptiID';
+  credentials: OptiIdAuthDataCredentials;
+}
+
+export interface OAuthAuthData {
+  provider: string;
+  credentials: OAuthProviderAuthDataCredentials;
+}
 
 /**
  * Auth data structure
  */
-export class OptiIdAuthData {
-
-  public constructor(
-    public provider: string,
-    public credentials: OptiIdAuthDataCredentials
-  ) {}
-}
+export type AuthData = OptiIdAuthData | OAuthAuthData;
 
 /**
  * Authentication requirements for an Opal tool

package/src/utils/ErrorFormatter.ts

@@ -0,0 +1,31 @@
+import { Response, Headers } from '@zaiusinc/app-sdk';
+import { ToolError } from '../types/ToolError';
+
+/**
+ * Format an error as RFC 9457 Problem Details response
+ * @param error The error to format (ToolError or generic Error)
+ * @param instance URI reference identifying the specific occurrence (typically request path)
+ * @returns RFC 9457 compliant Response
+ */
+export function formatErrorResponse(error: unknown, instance: string): Response {
+  if (error instanceof ToolError) {
+    return new Response(
+      error.status,
+      error.toProblemDetails(instance),
+      new Headers([['content-type', 'application/problem+json']])
+    );
+  }
+
+  // Fallback for generic errors
+  const message = error instanceof Error ? error.message : 'An unexpected error occurred';
+  return new Response(
+    500,
+    {
+      title: 'Internal Server Error',
+      status: 500,
+      detail: message,
+      instance
+    },
+    new Headers([['content-type', 'application/problem+json']])
+  );
+}