@optimizely-opal/opal-tool-ocp-sdk 1.0.0-beta.3 → 1.0.0-beta.5

package/README.md

@@ -317,6 +317,119 @@ export class MyToolFunction extends ToolFunction {
 }
 ```
 
+## Error Handling
+
+The SDK provides RFC 9457 Problem Details compliant error handling through the `ToolError` class. This allows you to throw errors with custom HTTP status codes and detailed error information.
+
+### ToolError Class
+
+```typescript
+class ToolError extends Error {
+  constructor(
+    message: string,      // Error message (used as "title" in RFC 9457)
+    status?: number,      // HTTP status code (default: 500)
+    detail?: string       // Detailed error description (optional)
+  )
+}
+```
+
+### Usage Examples
+
+```typescript
+import { ToolFunction, tool, ToolError, ParameterType } from '@optimizely-opal/opal-tool-ocp-sdk';
+
+
+// Throw a 404 error
+throw new ToolError(
+  'Task not found',
+  404,
+  `No task exists with ID: ${params.taskId}`
+);
+
+// Throw a 400 error for invalid input
+throw new ToolError(
+  'Invalid priority',
+  400,
+  `Priority must be one of: ${validPriorities.join(', ')}`
+);
+```
+
+### Error Response Format
+
+When a `ToolError` is thrown, the SDK automatically formats it as an RFC 9457 Problem Details response:
+
+```json
+{
+  "title": "Task not found",
+  "status": 404,
+  "detail": "No task exists with ID: task-123",
+  "instance": "/get-task"
+}
+```
+
+### Validation Errors with Multiple Fields
+
+You can also throw `ToolError` with an `errors` array for validation scenarios with multiple field errors:
+
+```typescript
+import { ToolError } from '@optimizely-opal/opal-tool-ocp-sdk';
+
+// Validate multiple fields
+const validationErrors = [];
+
+if (!email.includes('@')) {
+  validationErrors.push({
+    field: 'email',
+    message: 'Invalid email format'
+  });
+}
+
+if (age < 0) {
+  validationErrors.push({
+    field: 'age',
+    message: 'Age must be a positive number'
+  });
+}
+
+if (validationErrors.length > 0) {
+  throw new ToolError(
+    'Validation failed',
+    400,
+    "See 'errors' field for details.",
+    validationErrors
+  );
+}
+```
+
+This will return:
+
+```json
+{
+  "title": "Validation failed",
+  "status": 400,
+  "detail": "See 'errors' field for details.",
+  "instance": "/create-user",
+  "errors": [
+    {
+      "field": "email",
+      "message": "Invalid email format"
+    },
+    {
+      "field": "age",
+      "message": "Age must be a positive number"
+    }
+  ]
+}
+```
+
+**Response Headers:**
+- `Content-Type: application/problem+json`
+- HTTP status code matches the `ToolError` status
+
+**Note:**
+- If a regular `Error` (not `ToolError`) is thrown, it will be automatically wrapped in a 500 response with RFC 9457 format
+- Parameter validation is automatic and uses this same format when validation fails
+
 ## API Reference
 
 ### Handler Function Signatures
@@ -399,6 +512,7 @@ Key model classes with generic type support:
 - `AuthRequirement` - Defines authentication needs
 - `InteractionResult` - Response from interactions
 - `OptiIdAuthData` - OptiID specific authentication data
+- `ToolError` - Custom error class for RFC 9457 Problem Details error responses with configurable HTTP status codes
 
 ## Discovery and Ready Endpoints
 

package/dist/auth/AuthUtils.d.ts

@@ -3,7 +3,7 @@ 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
+ * @returns object with authData and accessToken, or null if auth is missing
  */
 export declare function extractAuthData(request: any): {
     authData: OptiIdAuthData;
@@ -13,14 +13,14 @@ export declare function extractAuthData(request: any): {
  * Authenticate a request for regular functions (with organization validation)
  *
  * @param request - The incoming request
- * @returns true if authentication and authorization succeed
+ * @throws {ToolError} If authentication or authorization fails
  */
-export declare function authenticateRegularRequest(request: any): Promise<boolean>;
+export declare function authenticateRegularRequest(request: any): Promise<void>;
 /**
  * Authenticate a request for global functions (without organization validation)
  *
  * @param request - The incoming request
- * @returns true if authentication succeeds
+ * @throws {ToolError} If authentication fails
  */
-export declare function authenticateGlobalRequest(request: any): Promise<boolean>;
+export declare function authenticateGlobalRequest(request: any): Promise<void>;
 //# sourceMappingURL=AuthUtils.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"AuthUtils.d.ts","sourceRoot":"","sources":["../../src/auth/AuthUtils.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AA4BjD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,GAAG,GAAG;IAAE,QAAQ,EAAE,cAAc,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAiBtG;AA+ED;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAE5E;AAED;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAE3E"}

package/dist/auth/AuthUtils.js

@@ -5,56 +5,89 @@ exports.authenticateRegularRequest = authenticateRegularRequest;
 exports.authenticateGlobalRequest = authenticateGlobalRequest;
 const app_sdk_1 = require("@zaiusinc/app-sdk");
 const TokenVerifier_1 = require("./TokenVerifier");
+const ToolError_1 = require("../types/ToolError");
 /**
  * Validate the OptiID access token
  *
  * @param accessToken - The access token to validate
- * @returns true if the token is valid
+ * @throws {ToolError} If token validation fails
  */
 async function validateAccessToken(accessToken) {
     try {
         if (!accessToken) {
-            return false;
+            throw new ToolError_1.ToolError('Forbidden', 403, 'OptiID access token is required');
         }
         const tokenVerifier = await (0, TokenVerifier_1.getTokenVerifier)();
-        return await tokenVerifier.verify(accessToken);
+        const isValid = await tokenVerifier.verify(accessToken);
+        if (!isValid) {
+            throw new ToolError_1.ToolError('Forbidden', 403, 'Invalid OptiID access token');
+        }
     }
     catch (error) {
+        if (error instanceof ToolError_1.ToolError) {
+            throw error;
+        }
         app_sdk_1.logger.error('OptiID token validation failed:', error);
-        return false;
+        throw new ToolError_1.ToolError('Forbidden', 403, 'Token verification failed');
     }
 }
 /**
  * Extract and validate basic OptiID authentication data from request
  *
  * @param request - The incoming request
- * @returns object with authData and accessToken, or null if invalid
+ * @returns object with authData and accessToken, or null if auth is missing
  */
 function extractAuthData(request) {
     const authData = request?.bodyJSON?.auth;
+    if (!authData) {
+        return null;
+    }
+    if (authData?.provider?.toLowerCase() !== 'optiid') {
+        return null;
+    }
     const accessToken = authData?.credentials?.access_token;
-    if (!accessToken || authData?.provider?.toLowerCase() !== 'optiid') {
+    if (!accessToken) {
         return null;
     }
     return { authData, accessToken };
 }
+/**
+ * Extract and validate auth data with error throwing for authentication flow
+ *
+ * @param request - The incoming request
+ * @returns object with authData and accessToken
+ * @throws {ToolError} If auth data is invalid or missing
+ */
+function extractAndValidateAuthData(request) {
+    const authData = request?.bodyJSON?.auth;
+    if (!authData) {
+        throw new ToolError_1.ToolError('Forbidden', 403, 'Authentication data is required');
+    }
+    if (authData?.provider?.toLowerCase() !== 'optiid') {
+        throw new ToolError_1.ToolError('Forbidden', 403, 'Only OptiID authentication provider is supported');
+    }
+    const accessToken = authData?.credentials?.access_token;
+    if (!accessToken) {
+        throw new ToolError_1.ToolError('Forbidden', 403, 'OptiID access token is required');
+    }
+    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
+ * @throws {ToolError} If organization ID is invalid or missing
  */
 function validateOrganizationId(customerId) {
     if (!customerId) {
         app_sdk_1.logger.error('Organisation ID is required but not provided');
-        return false;
+        throw new ToolError_1.ToolError('Forbidden', 403, 'Organization ID is required');
     }
     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;
+        throw new ToolError_1.ToolError('Forbidden', 403, 'Organization ID does not match');
     }
-    return true;
 }
 /**
  * Check if a request should skip authentication (discovery/ready endpoints)
@@ -70,40 +103,35 @@ function shouldSkipAuth(request) {
  *
  * @param request - The incoming request
  * @param validateOrg - Whether to validate organization ID
- * @returns true if authentication succeeds
+ * @throws {ToolError} If authentication fails
  */
 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;
+        return;
     }
-    const { authData, accessToken } = authInfo;
+    const { authData, accessToken } = extractAndValidateAuthData(request);
     // Validate organization ID if required
-    if (validateOrg && !validateOrganizationId(authData.credentials?.customer_id)) {
-        return false;
+    if (validateOrg) {
+        validateOrganizationId(authData.credentials?.customer_id);
     }
-    return await validateAccessToken(accessToken);
+    await validateAccessToken(accessToken);
 }
 /**
  * Authenticate a request for regular functions (with organization validation)
  *
  * @param request - The incoming request
- * @returns true if authentication and authorization succeed
+ * @throws {ToolError} If authentication or authorization fails
  */
 async function authenticateRegularRequest(request) {
-    return await authenticateRequest(request, true);
+    await authenticateRequest(request, true);
 }
 /**
  * Authenticate a request for global functions (without organization validation)
  *
  * @param request - The incoming request
- * @returns true if authentication succeeds
+ * @throws {ToolError} If authentication fails
  */
 async function authenticateGlobalRequest(request) {
-    return await authenticateRequest(request, false);
+    await authenticateRequest(request, false);
 }
 //# sourceMappingURL=AuthUtils.js.map

package/dist/auth/AuthUtils.js.map

@@ -1 +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"}
+{"version":3,"file":"AuthUtils.js","sourceRoot":"","sources":["../../src/auth/AuthUtils.ts"],"names":[],"mappings":"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"}