feat(kleros-sdk): better-error-handling-and-optimisations

kleros-sdk/src/dataMappings/actions/callAction.ts

@@ -2,12 +2,13 @@ import { parseAbiItem } from "viem";
 import { AbiCallMapping } from "../utils/actionTypes";
 import { createResultObject } from "../utils/createResultObject";
 import { getPublicClient } from "../../sdk";
+import { SdkNotConfiguredError } from "../../errors";
 
 export const callAction = async (mapping: AbiCallMapping) => {
   const publicClient = getPublicClient();
 
   if (!publicClient) {
-    throw new Error("SDK not configured. Please call `configureSDK` before using.");
+    throw new SdkNotConfiguredError();
   }
 
   const { abi: source, address, functionName, args, seek, populate } = mapping;

kleros-sdk/src/dataMappings/actions/eventAction.ts

@@ -2,12 +2,13 @@ import { parseAbiItem, type AbiEvent } from "viem";
 import { AbiEventMapping } from "../utils/actionTypes";
 import { createResultObject } from "../utils/createResultObject";
 import { getPublicClient } from "../../sdk";
+import { SdkNotConfiguredError } from "../../errors";
 
 export const eventAction = async (mapping: AbiEventMapping) => {
   const publicClient = getPublicClient();
 
   if (!publicClient) {
-    throw new Error("SDK not configured. Please call `configureSDK` before using.");
+    throw new SdkNotConfiguredError();
   }
 
   const { abi: source, address, eventFilter, seek, populate } = mapping;

kleros-sdk/src/dataMappings/actions/fetchIpfsJsonAction.ts

@@ -1,4 +1,5 @@
 import { MAX_BYTE_SIZE } from "../../consts";
+import { RequestError } from "../../errors";
 import { FetchIpfsJsonMapping } from "../utils/actionTypes";
 import { createResultObject } from "../utils/createResultObject";
 
@@ -13,23 +14,23 @@ export const fetchIpfsJsonAction = async (mapping: FetchIpfsJsonMapping) => {
   } else if (!ipfsUri.startsWith("http")) {
     httpUri = `https://ipfs.io/ipfs/${ipfsUri}`;
   } else {
-    throw new Error("Invalid IPFS URI format");
+    throw new RequestError("Invalid IPFS URI format", httpUri);
   }
 
   const response = await fetch(httpUri, { method: "GET" });
 
   if (!response.ok) {
-    throw new Error("Failed to fetch data from IPFS");
+    throw new RequestError("Failed to fetch data from IPFS", httpUri);
   }
 
   const contentLength = response.headers.get("content-length");
   if (contentLength && parseInt(contentLength) > MAX_BYTE_SIZE) {
-    throw new Error("Response size is too large");
+    throw new RequestError("Response size is too large", httpUri);
   }
 
   const contentType = response.headers.get("content-type");
   if (!contentType || !contentType.includes("application/json")) {
-    throw new Error("Fetched data is not JSON");
+    throw new RequestError("Fetched data is not JSON", httpUri);
   }
 
   const data = await response.json();

kleros-sdk/src/dataMappings/executeActions.ts

@@ -1,3 +1,4 @@
+import { UnsupportedActionError } from "../errors";
 import { callAction } from "./actions/callAction";
 import { eventAction } from "./actions/eventAction";
 import { fetchIpfsJsonAction } from "./actions/fetchIpfsJsonAction";
@@ -41,7 +42,7 @@ export const executeAction = async (
       mapping = validateRealityMapping(mapping);
       return await retrieveRealityData(mapping.realityQuestionID, context.arbitrableAddress as Address);
     default:
-      throw new Error(`Unsupported action type: ${JSON.stringify(mapping)}`);
+      throw new UnsupportedActionError(`Unsupported action type: ${JSON.stringify(mapping)}`);
   }
 };
 

kleros-sdk/src/dataMappings/retrieveRealityData.ts

@@ -1,3 +1,4 @@
+import { InvalidContextError, NotFoundError } from "../errors";
 import { executeAction } from "./executeActions";
 import { AbiEventMapping } from "./utils/actionTypes";
 
@@ -11,7 +12,7 @@ export type RealityAnswer = {
 
 export const retrieveRealityData = async (realityQuestionID: string, arbitrable?: `0x${string}`) => {
   if (!arbitrable) {
-    throw new Error("No arbitrable address provided");
+    throw new InvalidContextError("No arbitrable address provided");
   }
   const questionMapping: AbiEventMapping = {
     type: "abi/event",
@@ -67,8 +68,12 @@ export const retrieveRealityData = async (realityQuestionID: string, arbitrable?
   const templateData = await executeAction(templateMapping);
   console.log("templateData", templateData);
 
-  if (!templateData || !questionData) {
-    throw new Error("Failed to retrieve template or question data");
+  if (!templateData) {
+    throw new NotFoundError("Template Data", "Failed to retrieve template data");
+  }
+
+  if (!questionData) {
+    throw new NotFoundError("Question Data", "Failed to retrieve question data");
   }
 
   const rc_question = require("@reality.eth/reality-eth-lib/formatters/question.js");

kleros-sdk/src/dataMappings/utils/actionTypeValidators.ts

@@ -1,3 +1,4 @@
+import { InvalidMappingError } from "../../errors";
 import {
   SubgraphMapping,
   AbiEventMapping,
@@ -9,43 +10,37 @@ import {
 } from "./actionTypes";
 
 export const validateSubgraphMapping = (mapping: ActionMapping) => {
-  if ((mapping as SubgraphMapping).endpoint === undefined) {
-    throw new Error("Invalid mapping for graphql action.");
-  }
-  return mapping as SubgraphMapping;
+  return validateMapping(mapping as SubgraphMapping, ["endpoint"]);
 };
 
 export const validateAbiEventMapping = (mapping: ActionMapping) => {
-  if ((mapping as AbiEventMapping).abi === undefined || (mapping as AbiEventMapping).eventFilter === undefined) {
-    throw new Error("Invalid mapping for abi/event action.");
-  }
-  return mapping as AbiEventMapping;
+  return validateMapping(mapping as AbiEventMapping, ["abi", "eventFilter"]);
 };
 
 export const validateAbiCallMapping = (mapping: ActionMapping) => {
-  if ((mapping as AbiCallMapping).abi === undefined || (mapping as AbiCallMapping).functionName === undefined) {
-    throw new Error("Invalid mapping for abi/call action.");
-  }
-  return mapping as AbiCallMapping;
+  return validateMapping(mapping as AbiCallMapping, ["abi", "functionName"]);
 };
 
 export const validateJsonMapping = (mapping: ActionMapping) => {
-  if ((mapping as JsonMapping).value === undefined) {
-    throw new Error("Invalid mapping for json action.");
-  }
-  return mapping as JsonMapping;
+  return validateMapping(mapping as JsonMapping, ["value"]);
 };
 
 export const validateFetchIpfsJsonMapping = (mapping: ActionMapping) => {
-  if ((mapping as FetchIpfsJsonMapping).ipfsUri === undefined) {
-    throw new Error("Invalid mapping for fetch/ipfs/json action.");
-  }
-  return mapping as FetchIpfsJsonMapping;
+  return validateMapping(mapping as FetchIpfsJsonMapping, ["ipfsUri"]);
 };
 
 export const validateRealityMapping = (mapping: ActionMapping) => {
   if (mapping.type !== "reality" || typeof (mapping as RealityMapping).realityQuestionID !== "string") {
-    throw new Error("Invalid mapping for reality action.");
+    throw new InvalidMappingError("Expected field 'realityQuestionID' to be a string.");
   }
   return mapping as RealityMapping;
 };
+
+const validateMapping = <T extends ActionMapping>(mapping: T, requiredFields: (keyof T)[]) => {
+  for (const field of requiredFields) {
+    if (mapping[field] === undefined) {
+      throw new InvalidMappingError(`${field.toString()} is required for ${mapping.type}`);
+    }
+  }
+  return mapping;
+};

kleros-sdk/src/dataMappings/utils/populateTemplate.ts

@@ -1,6 +1,7 @@
 import mustache from "mustache";
 import { DisputeDetails } from "./disputeDetailsTypes";
 import DisputeDetailsSchema from "./disputeDetailsSchema";
+import { InvalidFormatError } from "../../errors";
 
 export const populateTemplate = (mustacheTemplate: string, data: any): DisputeDetails => {
   const render = mustache.render(mustacheTemplate, data);
@@ -9,7 +10,7 @@ export const populateTemplate = (mustacheTemplate: string, data: any): DisputeDe
   const validation = DisputeDetailsSchema.safeParse(dispute);
   if (!validation.success) {
     console.error("Validation errors:", validation.error.errors, "\n\nDispute details:", `${JSON.stringify(dispute)}`);
-    throw new Error("Invalid dispute details format");
+    throw new InvalidFormatError("Invalid dispute details format");
   }
   console.log(dispute);
 

kleros-sdk/src/dataMappings/utils/replacePlaceholdersWithValues.ts

@@ -1,6 +1,7 @@
 import mustache from "mustache";
 import retrieveVariables from "./retrieveVariables";
 import { ActionMapping } from "./actionTypes";
+import { InvalidContextError } from "../../errors";
 
 export function replacePlaceholdersWithValues(
   mapping: ActionMapping,
@@ -34,7 +35,7 @@ const validateContext = (template: string, context: Record<string, unknown>) =>
   const variables = retrieveVariables(template);
 
   variables.forEach((variable) => {
-    if (!context[variable]) throw new Error(`Expected key :  "${variable}" to be provided in context.`);
+    if (!context[variable]) throw new InvalidContextError(`Expected key "${variable}" to be provided in context.`);
   });
   return true;
 };

kleros-sdk/src/errors/index.ts

@@ -0,0 +1,82 @@
+export class InvalidContextError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "InvalidContextError";
+
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+}
+
+export class InvalidMappingError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "InvalidMappingError";
+
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+}
+
+export class NotFoundError extends Error {
+  public resourceName: string;
+
+  constructor(resourceName: string, message: string) {
+    super(message);
+    this.name = "NotFoundError";
+    this.resourceName = resourceName;
+
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+}
+
+export class RequestError extends Error {
+  public endpoint: string | undefined;
+
+  constructor(message: string, endpoint?: string) {
+    super(message);
+    this.name = "RequestError";
+    this.endpoint = endpoint;
+
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+}
+
+export class UnsupportedActionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "UnsupportedActionError";
+
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+}
+
+export class InvalidFormatError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "InvalidFormatError";
+
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+}
+
+export class SdkNotConfiguredError extends Error {
+  constructor() {
+    super("SDK not configured. Please call `configureSDK` before using.");
+    this.name = "SdkNotConfiguredError";
+
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+}

kleros-sdk/src/requests/fetchDisputeDetails.ts

@@ -1,4 +1,5 @@
 import { request } from "graphql-request";
+import { RequestError } from "../errors";
 
 type DisputeDetailsQueryResponse = {
   dispute: {
@@ -13,8 +14,8 @@ type DisputeDetailsQueryResponse = {
 
 const fetchDisputeDetails = async (endpoint: string, id: bigint) => {
   const query = `
-    query DisputeDetails {
-    dispute(id: ${Number(id)}) {
+    query DisputeDetails($id: ID!)  {
+    dispute(id: $id) {
         arbitrated {
             id
         }
@@ -24,11 +25,15 @@ const fetchDisputeDetails = async (endpoint: string, id: bigint) => {
     }
   }
 `;
+  const variables = { id: Number(id) };
 
   try {
-    return await request<DisputeDetailsQueryResponse>(endpoint, query);
+    return await request<DisputeDetailsQueryResponse>(endpoint, query, variables);
   } catch (error: any) {
-    throw new Error(`Error querying Dispute Details , endpoint : ${endpoint}, message : ${error?.message}`);
+    if (error instanceof Error) {
+      throw new RequestError(`Error querying Dispute Details: ${error.message}`, endpoint);
+    }
+    throw new RequestError("An unknown error occurred while querying Dispute Details", endpoint);
   }
 };
 

kleros-sdk/src/requests/fetchDisputeTemplateFromId.ts

@@ -1,4 +1,5 @@
 import { request } from "graphql-request";
+import { RequestError } from "../errors";
 
 type DisputeTemplateQueryResponse = {
   disputeTemplate: {
@@ -9,18 +10,22 @@ type DisputeTemplateQueryResponse = {
 
 const fetchDisputeTemplateFromId = async (endpoint: string, id: number) => {
   const query = `
-    query DisputeTemplate {
-        disputeTemplate(id: ${id}) {
+    query DisputeTemplate ($id: ID!) {
+        disputeTemplate(id: $id) {
             templateData
             templateDataMappings
         }
     }
 `;
 
+  const variables = { id: id.toString() };
   try {
-    return await request<DisputeTemplateQueryResponse>(endpoint, query);
+    return await request<DisputeTemplateQueryResponse>(endpoint, query, variables);
   } catch (error: any) {
-    throw new Error(`Error querying Dispute Template Registry , endpoint : ${endpoint}, message : ${error?.message}`);
+    if (error instanceof Error) {
+      throw new RequestError(`Error querying Dispute Template: ${error.message}`, endpoint);
+    }
+    throw new RequestError("An unknown error occurred while querying Dispute Template", endpoint);
   }
 };
 

kleros-sdk/src/sdk.ts

@@ -1,5 +1,6 @@
 import { createPublicClient, type PublicClient } from "viem";
 import { SdkConfig } from "./types";
+import { SdkNotConfiguredError } from "./errors";
 
 let publicClient: PublicClient | undefined;
 
@@ -11,7 +12,7 @@ export const configureSDK = (config: SdkConfig) => {
 
 export const getPublicClient = (): PublicClient | undefined => {
   if (!publicClient) {
-    throw new Error("SDK not configured. Please call `configureSDK` before using.");
+    throw new SdkNotConfiguredError();
   }
   return publicClient;
 };