Add error callback and error redirect url (#71)

Author: predatorx7

src/Reclaim.ts

@@ -32,7 +32,8 @@ import {
     SetParamsError,
     SetSignatureError,
     SignatureGeneratingError,
-    SignatureNotFoundError
+    SignatureNotFoundError,
+    ErrorDuringVerificationError
 } from './utils/errors'
 import { validateContext, validateFunctionParams, validateParameters, validateSignature, validateURL, validateModalOptions } from './utils/validationUtils'
 import { fetchStatusUrl, initSession, updateSession } from './utils/sessionUtils'
@@ -166,6 +167,8 @@ const emptyTemplateData: TemplateData = {
     context: '',
     parameters: {},
     redirectUrl: '',
+    errorCallbackUrl: '',
+    errorRedirectUrl: '',
     acceptAiProviders: false,
     sdkVersion: '',
     providerVersion: '',
@@ -185,6 +188,8 @@ export class ReclaimProofRequest {
     private resolvedProviderVersion?: string;
     private parameters: { [key: string]: string };
     private redirectUrl?: string;
+    private errorCallbackUrl?: TemplateData['errorCallbackUrl'];
+    private errorRedirectUrl?: TemplateData['errorRedirectUrl'];
     private intervals: Map<string, NodeJS.Timer> = new Map();
     private timeStamp: string;
     private sdkVersion: string;
@@ -370,6 +375,8 @@ export class ReclaimProofRequest {
                 parameters,
                 signature,
                 redirectUrl,
+                errorCallbackUrl,
+                errorRedirectUrl,
                 timeStamp,
                 timestamp,
                 appCallbackUrl,
@@ -405,6 +412,14 @@ export class ReclaimProofRequest {
                 validateURL(appCallbackUrl, 'fromJsonString');
             }
 
+            if (errorRedirectUrl) {
+                validateURL(errorRedirectUrl, 'fromJsonString');
+            }
+
+            if (errorCallbackUrl) {
+                validateURL(errorCallbackUrl, 'fromJsonString');
+            }
+
             if (context) {
                 validateContext(context);
             }
@@ -450,6 +465,8 @@ export class ReclaimProofRequest {
             proofRequestInstance.resolvedProviderVersion = resolvedProviderVersion;
             proofRequestInstance.modalOptions = modalOptions;
             proofRequestInstance.jsonProofResponse = jsonProofResponse ?? false;
+            proofRequestInstance.errorCallbackUrl = errorCallbackUrl;
+            proofRequestInstance.errorRedirectUrl = errorRedirectUrl;
             return proofRequestInstance
         } catch (error) {
             logger.info('Failed to parse JSON string in fromJsonString:', error);
@@ -500,6 +517,43 @@ export class ReclaimProofRequest {
         this.redirectUrl = url;
     }
 
+    /**
+     * Sets a custom callback URL where errors will be submitted via HTTP POST
+     *
+     * Errors will be HTTP POSTed with `header 'Content-Type': 'application/json'`.
+     * When a custom error callback URL is set, Reclaim will no longer receive errors upon submission,
+     * and listeners on the startSession method will not be triggered. Your application must
+     * coordinate with your backend to receive errors.
+     *
+     * @param url - The URL where errors should be submitted via HTTP POST
+     * @throws {InvalidParamError} When URL is invalid
+     *
+     * @example
+     * ```typescript
+     * proofRequest.setErrorCallbackUrl('https://your-backend.com/error-callback');
+     * ```
+     */
+    setErrorCallbackUrl(url: string): void {
+        validateURL(url, 'setErrorCallbackUrl')
+        this.errorCallbackUrl = url
+    }
+
+    /**
+     * Sets an error redirect URL where users will be redirected after error in verification process
+     *
+     * @param url - The URL where users should be redirected after error in verification process
+     * @throws {InvalidParamError} When URL is invalid
+     *
+     * @example
+     * ```typescript
+     * proofRequest.setErrorRedirectUrl('https://your-app.com/error');
+     * ```
+     */
+    setErrorRedirectUrl(url: string): void {
+        validateURL(url, 'setErrorRedirectUrl');
+        this.errorRedirectUrl = url;
+    }
+
     /**
      * Sets the claim creation type for the proof request
      *
@@ -661,6 +715,31 @@ export class ReclaimProofRequest {
         }
     }
 
+    /**
+     * Returns the currently configured error callback URL
+     *
+     * If no custom error callback URL was set via setErrorCallbackUrl(), this returns the default
+     * Reclaim service error callback URL with the current session ID.
+     *
+     * @returns The error callback URL where proofs will be submitted
+     * @throws {GetAppCallbackUrlError} When unable to retrieve the error callback URL
+     *
+     * @example
+     * ```typescript
+     * const callbackUrl = proofRequest.getErrorCallbackUrl();
+     * console.log('Errors will be sent to:', callbackUrl);
+     * ```
+     */
+    getErrorCallbackUrl(): string {
+        try {
+            validateFunctionParams([{ input: this.sessionId, paramName: 'sessionId', isString: true }], 'getErrorCallbackUrl');
+            return this.errorCallbackUrl || `${constants.DEFAULT_RECLAIM_ERROR_CALLBACK_URL}${this.sessionId}`
+        } catch (error) {
+            logger.info("Error getting error callback url", error)
+            throw new GetAppCallbackUrlError("Error getting error callback url", error as Error)
+        }
+    }
+
     /**
      * Returns the status URL for monitoring the current session
      *
@@ -782,6 +861,8 @@ export class ReclaimProofRequest {
             parameters: this.parameters,
             signature: this.signature,
             redirectUrl: this.redirectUrl,
+            errorCallbackUrl: this.errorCallbackUrl,
+            errorRedirectUrl: this.errorRedirectUrl,
             timestamp: this.timeStamp, // New field with correct spelling
             timeStamp: this.timeStamp, // @deprecated: Remove in future versions 
             options: this.options,
@@ -821,6 +902,8 @@ export class ReclaimProofRequest {
             resolvedProviderVersion: this.resolvedProviderVersion ?? '',
             parameters: this.parameters,
             redirectUrl: this.redirectUrl ?? '',
+            errorCallbackUrl: this.getErrorCallbackUrl(),
+            errorRedirectUrl: this.errorRedirectUrl,
             acceptAiProviders: this.options?.acceptAiProviders ?? false,
             sdkVersion: this.sdkVersion,
             jsonProofResponse: this.jsonProofResponse,
@@ -1208,6 +1291,10 @@ export class ReclaimProofRequest {
                     return; // Continue monitoring if under timeout
                 }
 
+                if (statusUrlResponse.session.statusV2 === SessionStatus.ERROR_SUBMISSION_FAILED || statusUrlResponse.session.statusV2 === SessionStatus.ERROR_SUBMITTED) {
+                    throw new ErrorDuringVerificationError();
+                }
+
                 const isDefaultCallbackUrl = this.getAppCallbackUrl() === `${constants.DEFAULT_RECLAIM_CALLBACK_URL}${this.sessionId}`;
 
                 if (isDefaultCallbackUrl) {

src/utils/constants.ts

@@ -12,6 +12,11 @@ export const constants = {
         return `${BACKEND_BASE_URL}/api/sdk/callback?callbackId=`;
     },
 
+    // Default error callback URL for Reclaim protocol
+    get DEFAULT_RECLAIM_ERROR_CALLBACK_URL() {
+        return `${BACKEND_BASE_URL}/api/sdk/error-callback?callbackId=`;
+    },
+
     // Default status URL for Reclaim sessions
     get DEFAULT_RECLAIM_STATUS_URL() {
         return `${BACKEND_BASE_URL}/api/sdk/session/`;

src/utils/errors.ts

@@ -37,4 +37,5 @@ export const SetSignatureError = createErrorClass('SetSignatureError');
 export const GetAppCallbackUrlError = createErrorClass("GetAppCallbackUrlError");
 export const StatusUrlError = createErrorClass('StatusUrlError');
 export const InavlidParametersError = createErrorClass('InavlidParametersError');
-export const ProofSubmissionFailedError = createErrorClass('ProofSubmissionFailedError');
+export const ProofSubmissionFailedError = createErrorClass('ProofSubmissionFailedError');
+export const ErrorDuringVerificationError = createErrorClass('ErrorDuringVerificationError');

src/utils/types.ts

@@ -135,6 +135,8 @@ export enum SessionStatus {
   PROOF_SUBMITTED = 'PROOF_SUBMITTED',
   AI_PROOF_SUBMITTED = 'AI_PROOF_SUBMITTED',
   PROOF_SUBMISSION_FAILED = 'PROOF_SUBMISSION_FAILED',
+  ERROR_SUBMITTED = 'ERROR_SUBMITTED',
+  ERROR_SUBMISSION_FAILED = 'ERROR_SUBMISSION_FAILED',
   PROOF_MANUAL_VERIFICATION_SUBMITED = 'PROOF_MANUAL_VERIFICATION_SUBMITED',
 };
 
@@ -153,6 +155,8 @@ export type ProofPropertiesJSON = {
   timeStamp?: string;
   timestamp?: string; // new timestamp field
   appCallbackUrl?: string;
+  errorCallbackUrl?: TemplateData['errorCallbackUrl'];
+  errorRedirectUrl?: TemplateData['errorRedirectUrl'];
   claimCreationType?: ClaimCreationType;
   options?: ProofRequestOptions;
   sdkVersion: string;
@@ -171,6 +175,8 @@ export type TemplateData = {
   context: string;
   parameters: { [key: string]: string };
   redirectUrl: string;
+  errorCallbackUrl?: string | null;
+  errorRedirectUrl?: string | null;
   acceptAiProviders: boolean;
   sdkVersion: string;
   jsonProofResponse?: boolean;