feat: add custom errors (#480)

## Description

This PR adds custom error handling to this project by defining several
new error types. These errors are defined in the
packages/core/src/errors directory.

## What type of PR is this? (check all applicable)

- [x] 🍕 Feature (`feat:`)
- [ ] 🐛 Bug Fix (`fix:`)
- [ ] 📝 Documentation Update (`docs:`)
- [ ] 🎨 Style (`style:`)
- [ ] 🧑‍💻 Code Refactor (`refactor:`)
- [ ] 🔥 Performance Improvements (`perf:`)
- [ ] ✅ Test (`test:`)
- [ ] 🤖 Build (`build:`)
- [ ] 🔁 CI (`ci:`)
- [ ] 📦 Chore (`chore:`)
- [ ] ⏩ Revert (`revert:`)
- [ ] 🚀 Breaking Changes (`BREAKING CHANGE:`)

## Related Tickets & Documents
Fixes #468

## Added tests?

- [x] 👍 yes
- [ ] 🙅 no, because they aren't needed
- [ ] 🙋 no, because I need help


## Added to documentation?

- [ ] 📜 README.md
- [ ] 📓 Documentation
- [x] 🙅 no documentation needed

packages/core/scripts/contracts-check.ts

@@ -3,19 +3,23 @@ import path from "path";
 import { fileURLToPath } from "url";
 import { promisify } from "util";
 
+import { ContractsCheckError } from "../src/errors/config.js";
+
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
 const execAsync = promisify(exec);
 
 const outputFilePath = path.resolve(__dirname, "..", "src", "contracts.ts");
 
+const docsPath = "/nft-contracts";
+const docsSlug = "list-all-nft-contracts";
 async function run() {
   try {
     const { stderr } = await execAsync(`tsc --noEmit ${outputFilePath}`);
 
     if (stderr) {
-      throw new Error(stderr);
+      throw new ContractsCheckError(stderr, { docsPath, docsSlug });
     }
 
     console.log("Contracts file is valid TypeScript.");

packages/core/src/actions/account/account.ts

@@ -8,7 +8,9 @@ import {
 } from "starknet";
 
 import { SOLIS_ACCOUNT_CLASS_HASH } from "../../constants.js";
+import { AccountDeployFailedError } from "../../errors/actions.js";
 
+const docsPath = "sdk-core/create-account";
 /**
  * Creates a new account on the StarkNet testnet.
  * This function generates a private key, derives the corresponding public key,
@@ -53,11 +55,11 @@ export const createAccount = async (provider: ProviderInterface) => {
       addressSalt: publicKey
     });
   } catch (e) {
-    throw new Error(`Account deploy failed for ${address}`);
+    throw new AccountDeployFailedError(address, { docsPath });
   }
 
   if (!response) {
-    throw new Error(`Account deploy failed for ${address}`);
+    throw new AccountDeployFailedError(address, { docsPath });
   }
 
   const { transaction_hash, contract_address } = response;

packages/core/src/actions/fees/setArkFees.ts

@@ -1,6 +1,7 @@
 import { Account, cairo, CallData } from "starknet";
 
 import { Config } from "../../createConfig.js";
+import { InvalidFeesRatioError } from "../../errors/actions.js";
 import { validateFeesRatio } from "../../utils/index.js";
 
 interface Params {
@@ -11,7 +12,7 @@ interface Params {
 
 export const setArkFees = async (config: Config, params: Params) => {
   if (!validateFeesRatio(params.numerator, params.denominator)) {
-    throw new Error("Invalid fees ratio");
+    throw new InvalidFeesRatioError();
   }
 
   const result = await params.account.execute({

packages/core/src/actions/fees/setBrokerFees.ts

@@ -1,6 +1,7 @@
 import { Account, cairo, CallData } from "starknet";
 
 import { Config } from "../../createConfig.js";
+import { InvalidFeesRatioError } from "../../errors/actions.js";
 import { validateFeesRatio } from "../../utils/index.js";
 
 interface Params {
@@ -11,7 +12,7 @@ interface Params {
 
 export const setBrokerFees = async (config: Config, params: Params) => {
   if (!validateFeesRatio(params.numerator, params.denominator)) {
-    throw new Error("Invalid fees ratio");
+    throw new InvalidFeesRatioError();
   }
 
   const result = await params.brokerAccount.execute({

packages/core/src/actions/fees/setCollectionCreatorFees.ts

@@ -1,6 +1,7 @@
 import { Account, cairo, CallData } from "starknet";
 
 import { Config } from "../../createConfig.js";
+import { InvalidFeesRatioError } from "../../errors/actions.js";
 import { validateFeesRatio } from "../../utils/index.js";
 
 interface Params {
@@ -16,7 +17,7 @@ export const setCollectionCreatorFees = async (
   params: Params
 ) => {
   if (!validateFeesRatio(params.numerator, params.denominator)) {
-    throw new Error("Invalid fees ratio");
+    throw new InvalidFeesRatioError();
   }
 
   const result = await params.account.execute({

packages/core/src/actions/fees/setDefaultCreatorFees.ts

@@ -1,6 +1,7 @@
 import { Account, cairo, CallData } from "starknet";
 
 import { Config } from "../../createConfig.js";
+import { InvalidFeesRatioError } from "../../errors/actions.js";
 import { validateFeesRatio } from "../../utils/index.js";
 
 interface Params {
@@ -12,7 +13,7 @@ interface Params {
 
 export const setDefaultCreatorFees = async (config: Config, params: Params) => {
   if (!validateFeesRatio(params.numerator, params.denominator)) {
-    throw new Error("Invalid fees ratio");
+    throw new InvalidFeesRatioError();
   }
 
   const result = await params.account.execute({

packages/core/src/actions/order/createAuction.ts

@@ -8,6 +8,13 @@ import {
 } from "starknet";
 
 import { Config } from "../../createConfig.js";
+import {
+  EndDateTooFarError,
+  InvalidEndAmountError,
+  InvalidEndDateError,
+  InvalidStartAmountError,
+  InvalidStartDateError
+} from "../../errors/actions.js";
 import { OrderV1, RouteType } from "../../types/index.js";
 import { getOrderHashFromOrderV1 } from "../../utils/index.js";
 
@@ -29,6 +36,7 @@ export interface CreateAuctionResult {
   transactionHash: string;
 }
 
+const docsPath = "/sdk-core/create-auction";
 /**
  * Creates an Auction on the ArkProject.
  *
@@ -65,33 +73,23 @@ export async function createAuction(
   const maxEndedAt = now + 60 * 60 * 24 * 30;
 
   if (startedAt < now) {
-    throw new Error(
-      `Invalid start date. Start date (${startDate}) cannot be in the past.`
-    );
+    throw new InvalidStartDateError(startDate, { docsPath });
   }
 
   if (endedAt < startedAt) {
-    throw new Error(
-      `Invalid end date. End date (${endDate}) must be after the start date (${startDate}).`
-    );
+    throw new InvalidEndDateError({ endDate, startDate }, { docsPath });
   }
 
   if (endedAt > maxEndedAt) {
-    throw new Error(
-      `End date too far in the future. End date (${endDate}) exceeds the maximum allowed (${maxEndedAt}).`
-    );
+    throw new EndDateTooFarError({ endDate, maxEndedAt }, { docsPath });
   }
 
   if (startAmount === BigInt(0)) {
-    throw new Error(
-      "Invalid start amount. The start amount must be greater than zero."
-    );
+    throw new InvalidStartAmountError({ docsPath });
   }
 
   if (endAmount && endAmount < startAmount) {
-    throw new Error(
-      "Invalid end amount. The end amount must be greater than the start amount."
-    );
+    throw new InvalidEndAmountError({ docsPath });
   }
 
   const chainId = await config.starknetProvider.getChainId();

packages/core/src/actions/order/createCollectionOffer.ts

@@ -8,6 +8,12 @@ import {
 } from "starknet";
 
 import { Config } from "../../createConfig.js";
+import {
+  EndDateTooFarError,
+  InvalidEndDateError,
+  InvalidStartAmountError,
+  InvalidStartDateError
+} from "../../errors/actions.js";
 import { OrderV1, RouteType } from "../../types/index.js";
 import { getOrderHashFromOrderV1 } from "../../utils/index.js";
 import { getAllowance } from "../read/getAllowance.js";
@@ -28,6 +34,7 @@ export interface CreateCollectionOfferResult {
   transactionHash: string;
 }
 
+const docsPath = "/sdk-core/create-collection-offer";
 /**
  * Creates a collection offer on the ArkProject.
  *
@@ -62,27 +69,19 @@ async function createCollectionOffer(
   const maxEndedAt = now + 60 * 60 * 24 * 30;
 
   if (startedAt < now) {
-    throw new Error(
-      `Invalid start date. Start date (${startDate}) cannot be in the past.`
-    );
+    throw new InvalidStartDateError(startDate, { docsPath });
   }
 
   if (endedAt < startedAt) {
-    throw new Error(
-      `Invalid end date. End date (${endDate}) must be after the start date (${startDate}).`
-    );
+    throw new InvalidEndDateError({ endDate, startDate }, { docsPath });
   }
 
   if (endedAt > maxEndedAt) {
-    throw new Error(
-      `End date too far in the future. End date (${endDate}) exceeds the maximum allowed (${maxEndedAt}).`
-    );
+    throw new EndDateTooFarError({ endDate, maxEndedAt }, { docsPath });
   }
 
   if (amount === BigInt(0)) {
-    throw new Error(
-      "Invalid start amount. The start amount must be greater than zero."
-    );
+    throw new InvalidStartAmountError({ docsPath });
   }
 
   const chainId = await config.starknetProvider.getChainId();

packages/core/src/actions/order/createListing.ts

@@ -8,6 +8,12 @@ import {
 } from "starknet";
 
 import { Config } from "../../createConfig.js";
+import {
+  EndDateTooFarError,
+  InvalidEndDateError,
+  InvalidStartAmountError,
+  InvalidStartDateError
+} from "../../errors/actions.js";
 import { OrderV1, RouteType } from "../../types/index.js";
 import { getOrderHashFromOrderV1 } from "../../utils/index.js";
 
@@ -28,6 +34,7 @@ export interface CreateListingResult {
   transactionHash: string;
 }
 
+const docsPath = "/sdk-core/create-listing";
 /**
  * Creates a listing on the ArkProject.
  *
@@ -63,27 +70,19 @@ export async function createListing(
   const maxEndedAt = now + 60 * 60 * 24 * 30;
 
   if (startedAt < now) {
-    throw new Error(
-      `Invalid start date. Start date (${startDate}) cannot be in the past.`
-    );
+    throw new InvalidStartDateError(startDate, { docsPath });
   }
 
   if (endedAt < startedAt) {
-    throw new Error(
-      `Invalid end date. End date (${endDate}) must be after the start date (${startDate}).`
-    );
+    throw new InvalidEndDateError({ endDate, startDate }, { docsPath });
   }
 
   if (endedAt > maxEndedAt) {
-    throw new Error(
-      `End date too far in the future. End date (${endDate}) exceeds the maximum allowed (${maxEndedAt}).`
-    );
+    throw new EndDateTooFarError({ endDate, maxEndedAt }, { docsPath });
   }
 
   if (amount === BigInt(0)) {
-    throw new Error(
-      "Invalid start amount. The start amount must be greater than zero."
-    );
+    throw new InvalidStartAmountError({ docsPath });
   }
 
   const chainId = await config.starknetProvider.getChainId();

packages/core/src/actions/order/createOffer.ts

@@ -8,6 +8,12 @@ import {
 } from "starknet";
 
 import { Config } from "../../createConfig.js";
+import {
+  EndDateTooFarError,
+  InvalidEndDateError,
+  InvalidStartAmountError,
+  InvalidStartDateError
+} from "../../errors/actions.js";
 import { OrderV1, RouteType } from "../../types/index.js";
 import { getOrderHashFromOrderV1 } from "../../utils/index.js";
 import { getAllowance } from "../read/getAllowance.js";
@@ -29,6 +35,7 @@ export interface CreateOfferResult {
   transactionHash: string;
 }
 
+const docsPath = "/sdk-core/create-offer";
 /**
  * Creates a listing on the ArkProject.
  *
@@ -64,27 +71,19 @@ export async function createOffer(
   const maxEndedAt = now + 60 * 60 * 24 * 30;
 
   if (startedAt < Math.floor(Date.now() / 1000)) {
-    throw new Error(
-      `Invalid start date. Start date (${startDate}) cannot be in the past.`
-    );
+    throw new InvalidStartDateError(startDate, { docsPath });
   }
 
   if (endedAt < startedAt) {
-    throw new Error(
-      `Invalid end date. End date (${endDate}) must be after the start date (${startDate}).`
-    );
+    throw new InvalidEndDateError({ endDate, startDate }, { docsPath });
   }
 
   if (endedAt > maxEndedAt) {
-    throw new Error(
-      `End date too far in the future. End date (${endDate}) exceeds the maximum allowed (${maxEndedAt}).`
-    );
+    throw new EndDateTooFarError({ endDate, maxEndedAt }, { docsPath });
   }
 
   if (amount === BigInt(0)) {
-    throw new Error(
-      "Invalid start amount. The start amount must be greater than zero."
-    );
+    throw new InvalidStartAmountError({ docsPath });
   }
 
   const chainId = await config.starknetProvider.getChainId();

packages/core/src/actions/read/getAllowance.ts

@@ -1,6 +1,7 @@
 import { Contract } from "starknet";
 
 import { Config } from "../../createConfig.js";
+import { NoABIError } from "../../errors/actions.js";
 
 export const getAllowance = async (
   config: Config,
@@ -10,7 +11,7 @@ export const getAllowance = async (
   const { abi } =
     await config.starknetProvider.getClassAt(ERC20ContractAddress);
   if (abi === undefined) {
-    throw new Error("no abi.");
+    throw new NoABIError({ docsPath: "/sdk-core/fulfill-listing" });
   }
 
   const ERC20Contract = new Contract(

packages/core/src/actions/read/getNFTOwner.ts

@@ -1,6 +1,7 @@
 import { cairo, CallData, Contract } from "starknet";
 
 import { Config } from "../../createConfig.js";
+import { NoABIError } from "../../errors/actions.js";
 
 export const getNftOwner = async (
   config: Config,
@@ -9,7 +10,7 @@ export const getNftOwner = async (
 ) => {
   const { abi } = await config.starknetProvider.getClassAt(nftContractAddress);
   if (abi === undefined) {
-    throw new Error("no abi.");
+    throw new NoABIError({ docsPath: "/sdk-core/get-nft-owner" });
   }
 
   const nftContract = new Contract(

packages/core/src/actions/read/getOrder.ts

@@ -1,6 +1,7 @@
 import { CallData, Contract } from "starknet";
 
 import { Config } from "../../createConfig.js";
+import { NoABIError } from "../../errors/actions.js";
 
 interface GetOrderParameters {
   orderHash: bigint;
@@ -12,7 +13,7 @@ const getOrder = async (config: Config, parameters: GetOrderParameters) => {
     config.starknetExecutorContract
   );
   if (orderbookAbi === undefined) {
-    throw new Error("no abi.");
+    throw new NoABIError({ docsPath: "/sdk-core/get-order" });
   }
 
   const orderbookContract = new Contract(