@obolnetwork/obol-sdk 2.4.3 → 2.4.5

package/dist/cjs/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@obolnetwork/obol-sdk",
-    "version": "2.4.3",
+    "version": "2.4.5",
     "description": "A package for creating Distributed Validators using the Obol API.",
     "bugs": {
         "url": "https://github.com/obolnetwork/obol-sdk/issues"
@@ -23,7 +23,8 @@
         "lint": "eslint \"{src,test}/**/*.{js,ts}\" --fix",
         "lint-ci": "eslint \"{src,test}/**/*.{js,ts}\"",
         "prettier-ci": "prettier --check \"{src,test}/**/*.{js,ts}\"",
-        "prettier": "prettier --write \"{src,test}/**/*.{js,ts}\""
+        "prettier": "prettier --write \"{src,test}/**/*.{js,ts}\"",
+        "docs": "typedoc"
     },
     "main": "./dist/cjs/src/index.js",
     "module": "./dist/esm/src/index.js",
@@ -79,8 +80,8 @@
         "release-it": "^17.2.1",
         "ts-jest": "^28.0.8",
         "tsup": "^6.7.0",
-        "typedoc": "^0.25.7",
-        "typedoc-plugin-markdown": "^4.0.0-next.50",
+        "typedoc": "^0.28.0",
+        "typedoc-plugin-markdown": "^4.5.2",
         "typescript": "~5.3.3"
     },
     "engines": {

package/dist/cjs/src/incentives.js

@@ -12,8 +12,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Incentives = void 0;
 const utils_1 = require("./utils");
 const types_1 = require("./types");
-const incentivesHalpers_1 = require("./incentivesHalpers");
+const incentiveHelpers_1 = require("./incentiveHelpers");
 const constants_1 = require("./constants");
+/**
+ * Incentives can be used for fetching and claiming Obol incentives.
+ * @class
+ * @internal Access it through Client.incentives.
+ * @example
+ * const obolClient = new Client(config);
+ * await obolClient.incentives.claimIncentives(address);
+ */
 class Incentives {
     constructor(signer, chainId, request, provider) {
         this.signer = signer;
@@ -22,39 +30,49 @@ class Incentives {
         this.provider = provider;
     }
     /**
-     * Claims obol incentives from a Merkle Distributor contract.
+     * Claims Obol incentives from a Merkle Distributor contract using an address.
+     *
+     * This method automatically fetches incentive data and verifies whether the incentives have already been claimed.
+     * If `txHash` is `null`, it indicates that the incentives were already claimed.
+     *
+     * Note: This method is not yet enabled and will throw an error if called.
      *
      * @remarks
      * **⚠️ Important:**  If you're storing the private key in an `.env` file, ensure it is securely managed
      * and not pushed to version control.
      *
-     * @param {Object} incentivesData - The incentives data needed for claiming.
-     * @param {string} incentivesData.contractAddress - The address of the Merkle Distributor contract.
-     * @param {number} incentivesData.index - The index in the Merkle tree.
-     * @param {string} incentivesData.operatorAddress - The address of the operator.
-     * @param {number} incentivesData.amount - The amount to claim.
-     * @param {string[]} incentivesData.merkleProof - The Merkle proof.
-     * @returns {Promise<{ txHash: string }>} The transaction hash of the claim transaction.
-     * @throws Will throw an error if the contract is not available or the claim fails.
+     * @param {string} address - The address to claim incentives for
+     * @returns {Promise<ClaimIncentivesResponse>} The transaction hash or already claimed status
+     * @throws Will throw an error if the incentives data is not found or the claim fails
      *
+     * An example of how to use claimIncentives:
+     * [obolClient](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L281)
      */
-    claimIncentives(incentivesData) {
+    claimIncentives(address) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this.signer) {
                 throw new Error('Signer is required in claimIncentives');
             }
             try {
-                const isContractDeployed = yield (0, utils_1.isContractAvailable)(incentivesData.contractAddress, this.signer.provider);
+                const incentivesData = yield this.getIncentivesByAddress(address);
+                if (!(incentivesData === null || incentivesData === void 0 ? void 0 : incentivesData.contract_address)) {
+                    throw new Error(`No incentives found for address ${address}`);
+                }
+                const isContractDeployed = yield (0, utils_1.isContractAvailable)(incentivesData.contract_address, this.provider);
                 if (!isContractDeployed) {
-                    throw new Error(`Merkle Distributor contract is not available at address ${incentivesData.contractAddress}`);
+                    throw new Error(`Merkle Distributor contract is not available at address ${incentivesData.contract_address}`);
                 }
-                const { txHash } = yield (0, incentivesHalpers_1.claimIncentivesFromMerkleDistributor)({
+                const claimed = yield this.isClaimed(incentivesData.contract_address, incentivesData.index);
+                if (claimed) {
+                    return { txHash: null };
+                }
+                const { txHash } = yield (0, incentiveHelpers_1.claimIncentivesFromMerkleDistributor)({
                     signer: this.signer,
-                    contractAddress: incentivesData.contractAddress,
+                    contractAddress: incentivesData.contract_address,
                     index: incentivesData.index,
-                    operatorAddress: incentivesData.operatorAddress,
+                    operatorAddress: incentivesData.operator_address,
                     amount: incentivesData.amount,
-                    merkleProof: incentivesData.merkleProof,
+                    merkleProof: incentivesData.merkle_proof,
                 });
                 return { txHash };
             }
@@ -71,16 +89,22 @@ class Incentives {
      * @param {ETH_ADDRESS} index - operator index in merkle tree
      * @returns {Promise<boolean>} true if incentives are already claime
      *
+     *
+     * An example of how to use isClaimed:
+     * [obolClient](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L266)
      */
     isClaimed(contractAddress, index) {
         return __awaiter(this, void 0, void 0, function* () {
-            return yield (0, incentivesHalpers_1.isClaimedFromMerkleDistributor)(this.chainId, contractAddress, index, this.provider);
+            return yield (0, incentiveHelpers_1.isClaimedFromMerkleDistributor)(this.chainId, contractAddress, index, this.provider);
         });
     }
     /**
      * @param address - Operator address
      * @returns {Promise<IncentivesType>} The matched incentives from DB
      * @throws On not found if address not found.
+     *
+     * An example of how to use getIncentivesByAddress:
+     * [obolClient](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L250)
      */
     getIncentivesByAddress(address) {
         return __awaiter(this, void 0, void 0, function* () {

package/dist/cjs/src/index.js

@@ -23,7 +23,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Client = void 0;
+exports.Client = exports.Incentives = void 0;
 const ethers_1 = require("ethers");
 const uuid_1 = require("uuid");
 const base_js_1 = require("./base.js");
@@ -39,6 +39,8 @@ __exportStar(require("./types.js"), exports);
 __exportStar(require("./services.js"), exports);
 __exportStar(require("./verification/signature-validator.js"), exports);
 __exportStar(require("./verification/common.js"), exports);
+var incentives_js_2 = require("./incentives.js");
+Object.defineProperty(exports, "Incentives", { enumerable: true, get: function () { return incentives_js_2.Incentives; } });
 /**
  * Obol sdk Client can be used for creating, managing and activating distributed validators.
  */
@@ -59,7 +61,7 @@ class Client extends base_js_1.Base {
         // Use the provided provider, or fall back to signer.provider if available
         this.provider =
             provider !== null && provider !== void 0 ? provider : (signer && 'provider' in signer ? signer.provider : undefined);
-        this.incentives = new incentives_js_1.Incentives(this.signer, this.chainId, this.request.bind(this), (this.provider = provider));
+        this.incentives = new incentives_js_1.Incentives(this.signer, this.chainId, this.request.bind(this), this.provider);
     }
     /**
      * Accepts Obol terms and conditions to be able to create or update data.

package/dist/cjs/src/types.js

@@ -19,20 +19,11 @@ var FORK_MAPPING;
     /** Hoodi Chain. */
     FORK_MAPPING[FORK_MAPPING["0x10000910"] = 560048] = "0x10000910";
 })(FORK_MAPPING || (exports.FORK_MAPPING = FORK_MAPPING = {}));
-/**
- * Permitted Chain Names
- */
 exports.FORK_NAMES = {
-    /** Mainnet. */
     [FORK_MAPPING['0x00000000']]: 'mainnet',
-    /** Goerli/Prater. */
     [FORK_MAPPING['0x00001020']]: 'goerli',
-    /** Gnosis Chain. */
     [FORK_MAPPING['0x00000064']]: 'gnosis',
-    /** Holesky. */
     [FORK_MAPPING['0x01017000']]: 'holesky',
-    /** Sepolia. */
     [FORK_MAPPING['0x90000069']]: 'sepolia',
-    /** Hoodi. */
     [FORK_MAPPING['0x10000910']]: 'hoodi',
 };

package/dist/cjs/test/incentives.test.js

@@ -36,117 +36,145 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const ethers_1 = require("ethers");
 const index_1 = require("../src/index");
 const utils = __importStar(require("../src/utils"));
-const incentivesHelpers = __importStar(require("../src/incentivesHalpers"));
+const incentivesHelpers = __importStar(require("../src/incentiveHelpers"));
 const constants_1 = require("../src/constants");
+const globals_1 = require("@jest/globals");
 const mnemonic = (_b = (_a = ethers_1.ethers.Wallet.createRandom().mnemonic) === null || _a === void 0 ? void 0 : _a.phrase) !== null && _b !== void 0 ? _b : '';
 const privateKey = ethers_1.ethers.Wallet.fromPhrase(mnemonic).privateKey;
 const provider = new ethers_1.JsonRpcProvider('https://ethereum-holesky.publicnode.com');
 const wallet = new ethers_1.ethers.Wallet(privateKey, provider);
 const mockSigner = wallet.connect(provider);
 const baseUrl = 'https://obol-api-dev.gcp.obol.tech';
-global.fetch = jest.fn();
-describe('Client.incentives', () => {
+// Fix the type error by properly typing the mock function
+global.fetch = globals_1.jest.fn();
+(0, globals_1.describe)('Client.incentives', () => {
     let clientInstance;
     const mockIncentivesData = {
-        contractAddress: '0x1234567890abcdef1234567890abcdef12345678',
+        contract_address: '0x1234567890abcdef1234567890abcdef12345678',
         index: 5,
-        operatorAddress: '0xabcdef1234567890abcdef1234567890abcdef12',
-        amount: 1000000000000000000,
-        merkleProof: [
+        operator_address: '0xabcdef1234567890abcdef1234567890abcdef12',
+        amount: '1000000000000000000',
+        merkle_proof: [
             '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
             '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890',
         ],
     };
-    beforeEach(() => {
-        jest.clearAllMocks();
+    (0, globals_1.beforeEach)(() => {
+        globals_1.jest.clearAllMocks();
         clientInstance = new index_1.Client({ baseUrl, chainId: 17000 }, mockSigner);
         global.fetch.mockReset();
     });
-    test('claimIncentives should throw an error without signer', () => __awaiter(void 0, void 0, void 0, function* () {
+    (0, globals_1.test)('claimIncentives should throw an error without signer', () => __awaiter(void 0, void 0, void 0, function* () {
         const clientWithoutSigner = new index_1.Client({
             baseUrl,
             chainId: 17000,
         });
-        yield expect(clientWithoutSigner.incentives.claimIncentives(mockIncentivesData)).rejects.toThrow('Signer is required in claimIncentives');
+        yield (0, globals_1.expect)(clientWithoutSigner.incentives.claimIncentives(mockIncentivesData.operator_address)).rejects.toThrow('Signer is required in claimIncentives');
     }));
-    test('claimIncentives should throw an error if contract is not available', () => __awaiter(void 0, void 0, void 0, function* () {
-        jest
+    (0, globals_1.test)('claimIncentives should throw an error if contract is not available', () => __awaiter(void 0, void 0, void 0, function* () {
+        globals_1.jest
+            .spyOn(clientInstance.incentives, 'getIncentivesByAddress')
+            .mockResolvedValue(mockIncentivesData);
+        globals_1.jest.spyOn(clientInstance.incentives, 'isClaimed').mockResolvedValue(false);
+        globals_1.jest
             .spyOn(utils, 'isContractAvailable')
             .mockImplementation(() => __awaiter(void 0, void 0, void 0, function* () { return yield Promise.resolve(false); }));
-        yield expect(clientInstance.incentives.claimIncentives(mockIncentivesData)).rejects.toThrow(`Merkle Distributor contract is not available at address ${mockIncentivesData.contractAddress}`);
+        yield (0, globals_1.expect)(clientInstance.incentives.claimIncentives(mockIncentivesData.operator_address)).rejects.toThrow(`Merkle Distributor contract is not available at address ${mockIncentivesData.contract_address}`);
     }));
-    test('claimIncentives should return txHash on successful claim', () => __awaiter(void 0, void 0, void 0, function* () {
+    (0, globals_1.test)('claimIncentives should return txHash on successful claim', () => __awaiter(void 0, void 0, void 0, function* () {
         const mockTxHash = '0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef';
-        jest
+        globals_1.jest
+            .spyOn(clientInstance.incentives, 'getIncentivesByAddress')
+            .mockResolvedValue(mockIncentivesData);
+        globals_1.jest.spyOn(clientInstance.incentives, 'isClaimed').mockResolvedValue(false);
+        globals_1.jest
             .spyOn(utils, 'isContractAvailable')
             .mockImplementation(() => __awaiter(void 0, void 0, void 0, function* () { return yield Promise.resolve(true); }));
-        jest
+        globals_1.jest
             .spyOn(incentivesHelpers, 'claimIncentivesFromMerkleDistributor')
             .mockImplementation(() => __awaiter(void 0, void 0, void 0, function* () { return yield Promise.resolve({ txHash: mockTxHash }); }));
-        const result = yield clientInstance.incentives.claimIncentives(mockIncentivesData);
-        expect(result).toEqual({ txHash: mockTxHash });
-        expect(incentivesHelpers.claimIncentivesFromMerkleDistributor).toHaveBeenCalledWith({
+        const result = yield clientInstance.incentives.claimIncentives(mockIncentivesData.operator_address);
+        (0, globals_1.expect)(result).toEqual({ txHash: mockTxHash });
+        (0, globals_1.expect)(incentivesHelpers.claimIncentivesFromMerkleDistributor).toHaveBeenCalledWith({
             signer: mockSigner,
-            contractAddress: mockIncentivesData.contractAddress,
+            contractAddress: mockIncentivesData.contract_address,
             index: mockIncentivesData.index,
-            operatorAddress: mockIncentivesData.operatorAddress,
+            operatorAddress: mockIncentivesData.operator_address,
             amount: mockIncentivesData.amount,
-            merkleProof: mockIncentivesData.merkleProof,
+            merkleProof: mockIncentivesData.merkle_proof,
         });
     }));
-    test('claimIncentives should throw an error if helper function fails', () => __awaiter(void 0, void 0, void 0, function* () {
-        jest
+    (0, globals_1.test)('claimIncentives should return txHash as null when incentives are already claimed', () => __awaiter(void 0, void 0, void 0, function* () {
+        globals_1.jest
+            .spyOn(clientInstance.incentives, 'getIncentivesByAddress')
+            .mockResolvedValue(mockIncentivesData);
+        globals_1.jest.spyOn(clientInstance.incentives, 'isClaimed').mockResolvedValue(true);
+        const result = yield clientInstance.incentives.claimIncentives(mockIncentivesData.operator_address);
+        (0, globals_1.expect)(result).toEqual({ txHash: null });
+        (0, globals_1.expect)(incentivesHelpers.claimIncentivesFromMerkleDistributor).not.toHaveBeenCalled();
+    }));
+    (0, globals_1.test)('claimIncentives should throw an error if no incentives found for address', () => __awaiter(void 0, void 0, void 0, function* () {
+        globals_1.jest
+            .spyOn(clientInstance.incentives, 'getIncentivesByAddress')
+            .mockRejectedValue(new Error('No incentives found for address'));
+        yield (0, globals_1.expect)(clientInstance.incentives.claimIncentives(mockIncentivesData.operator_address)).rejects.toThrow('Failed to claim incentives: No incentives found for address');
+    }));
+    (0, globals_1.test)('claimIncentives should throw an error if helper function fails', () => __awaiter(void 0, void 0, void 0, function* () {
+        globals_1.jest
+            .spyOn(clientInstance.incentives, 'getIncentivesByAddress')
+            .mockResolvedValue(mockIncentivesData);
+        globals_1.jest.spyOn(clientInstance.incentives, 'isClaimed').mockResolvedValue(false);
+        globals_1.jest
             .spyOn(utils, 'isContractAvailable')
             .mockImplementation(() => __awaiter(void 0, void 0, void 0, function* () { return yield Promise.resolve(true); }));
-        jest
+        globals_1.jest
             .spyOn(incentivesHelpers, 'claimIncentivesFromMerkleDistributor')
             .mockImplementation(() => __awaiter(void 0, void 0, void 0, function* () {
             throw new Error('Helper function error');
         }));
-        yield expect(clientInstance.incentives.claimIncentives(mockIncentivesData)).rejects.toThrow('Failed to claim incentives: Helper function error');
+        yield (0, globals_1.expect)(clientInstance.incentives.claimIncentives(mockIncentivesData.operator_address)).rejects.toThrow('Failed to claim incentives: Helper function error');
     }));
-    test('incentives should be initialized with the same chainId as client', () => {
+    (0, globals_1.test)('incentives should be initialized with the same chainId as client', () => {
         const customChainId = 5;
         const clientWithCustomChain = new index_1.Client({ baseUrl, chainId: customChainId }, mockSigner);
-        expect(clientWithCustomChain.incentives.chainId).toBe(customChainId);
+        (0, globals_1.expect)(clientWithCustomChain.incentives.chainId).toBe(customChainId);
     });
-    test('isClaimed should return true when incentive is claimed', () => __awaiter(void 0, void 0, void 0, function* () {
-        jest
+    (0, globals_1.test)('isClaimed should return true when incentive is claimed', () => __awaiter(void 0, void 0, void 0, function* () {
+        globals_1.jest
             .spyOn(incentivesHelpers, 'isClaimedFromMerkleDistributor')
             .mockImplementation(() => __awaiter(void 0, void 0, void 0, function* () { return yield Promise.resolve(true); }));
-        const result = yield clientInstance.incentives.isClaimed(mockIncentivesData.contractAddress, mockIncentivesData.index);
-        expect(result).toBe(true);
-        expect(incentivesHelpers.isClaimedFromMerkleDistributor).toHaveBeenCalledWith(clientInstance.incentives.chainId, mockIncentivesData.contractAddress, mockIncentivesData.index, undefined);
+        const result = yield clientInstance.incentives.isClaimed(mockIncentivesData.contract_address, mockIncentivesData.index);
+        (0, globals_1.expect)(result).toBe(true);
+        (0, globals_1.expect)(incentivesHelpers.isClaimedFromMerkleDistributor).toHaveBeenCalledWith(clientInstance.incentives.chainId, mockIncentivesData.contract_address, mockIncentivesData.index, {});
     }));
-    test('isClaimed should return false when incentive is not claimed', () => __awaiter(void 0, void 0, void 0, function* () {
-        jest
+    (0, globals_1.test)('isClaimed should return false when incentive is not claimed', () => __awaiter(void 0, void 0, void 0, function* () {
+        globals_1.jest
             .spyOn(incentivesHelpers, 'isClaimedFromMerkleDistributor')
             .mockImplementation(() => __awaiter(void 0, void 0, void 0, function* () { return yield Promise.resolve(false); }));
-        const result = yield clientInstance.incentives.isClaimed(mockIncentivesData.contractAddress, mockIncentivesData.index);
-        expect(result).toBe(false);
+        const result = yield clientInstance.incentives.isClaimed(mockIncentivesData.contract_address, mockIncentivesData.index);
+        (0, globals_1.expect)(result).toBe(false);
     }));
-    test('isClaimed should throw an error if helper function fails', () => __awaiter(void 0, void 0, void 0, function* () {
-        jest
+    (0, globals_1.test)('isClaimed should throw an error if helper function fails', () => __awaiter(void 0, void 0, void 0, function* () {
+        globals_1.jest
             .spyOn(incentivesHelpers, 'isClaimedFromMerkleDistributor')
             .mockImplementation(() => __awaiter(void 0, void 0, void 0, function* () {
             throw new Error('Helper function error');
         }));
-        yield expect(clientInstance.incentives.isClaimed(mockIncentivesData.contractAddress, mockIncentivesData.index)).rejects.toThrow('Helper function error');
+        yield (0, globals_1.expect)(clientInstance.incentives.isClaimed(mockIncentivesData.contract_address, mockIncentivesData.index)).rejects.toThrow('Helper function error');
     }));
-    test('isClaimed should work with a provider and a without signer', () => __awaiter(void 0, void 0, void 0, function* () {
-        // Create a client without a signer
+    (0, globals_1.test)('isClaimed should work with a provider and a without signer', () => __awaiter(void 0, void 0, void 0, function* () {
         const clientWithoutSigner = new index_1.Client({
             baseUrl,
             chainId: 17000,
         }, undefined, provider);
-        jest
+        globals_1.jest
             .spyOn(incentivesHelpers, 'isClaimedFromMerkleDistributor')
             .mockImplementation(() => __awaiter(void 0, void 0, void 0, function* () { return yield Promise.resolve(true); }));
-        const result = yield clientWithoutSigner.incentives.isClaimed(mockIncentivesData.contractAddress, mockIncentivesData.index);
-        expect(result).toBe(true);
-        expect(incentivesHelpers.isClaimedFromMerkleDistributor).toHaveBeenCalledWith(clientWithoutSigner.incentives.chainId, mockIncentivesData.contractAddress, mockIncentivesData.index, provider);
+        const result = yield clientWithoutSigner.incentives.isClaimed(mockIncentivesData.contract_address, mockIncentivesData.index);
+        (0, globals_1.expect)(result).toBe(true);
+        (0, globals_1.expect)(incentivesHelpers.isClaimedFromMerkleDistributor).toHaveBeenCalledWith(clientWithoutSigner.incentives.chainId, mockIncentivesData.contract_address, mockIncentivesData.index, provider);
     }));
-    test('getIncentivesByAddress should make the correct API request', () => __awaiter(void 0, void 0, void 0, function* () {
+    (0, globals_1.test)('getIncentivesByAddress should make the correct API request', () => __awaiter(void 0, void 0, void 0, function* () {
         const mockAddress = '0x1234567890abcdef1234567890abcdef12345678';
         const mockIncentives = {
             operator_address: '0x8c00157cae72c4ed6a1f8bfb60205601f0252e26',
@@ -162,13 +190,13 @@ describe('Client.incentives', () => {
             headers: new Headers(),
         });
         const result = yield clientInstance.incentives.getIncentivesByAddress(mockAddress);
-        expect(result).toEqual(mockIncentives);
-        expect(global.fetch).toHaveBeenCalledWith(`${baseUrl}/${constants_1.DEFAULT_BASE_VERSION}/address/incentives/holesky/${mockAddress}`, expect.objectContaining({ method: 'GET' }));
+        (0, globals_1.expect)(result).toEqual(mockIncentives);
+        (0, globals_1.expect)(global.fetch).toHaveBeenCalledWith(`${baseUrl}/${constants_1.DEFAULT_BASE_VERSION}/address/incentives/holesky/${mockAddress}`, globals_1.expect.objectContaining({ method: 'GET' }));
     }));
-    test('getIncentivesByAddress should handle API errors', () => __awaiter(void 0, void 0, void 0, function* () {
+    (0, globals_1.test)('getIncentivesByAddress should handle API errors', () => __awaiter(void 0, void 0, void 0, function* () {
         const mockAddress = '0x1234567890abcdef1234567890abcdef12345678';
         global.fetch.mockRejectedValue(new Error('Network error'));
-        yield expect(clientInstance.incentives.getIncentivesByAddress(mockAddress)).rejects.toThrow();
-        expect(global.fetch).toHaveBeenCalled();
+        yield (0, globals_1.expect)(clientInstance.incentives.getIncentivesByAddress(mockAddress)).rejects.toThrow();
+        (0, globals_1.expect)(global.fetch).toHaveBeenCalled();
     }));
 });

package/dist/esm/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@obolnetwork/obol-sdk",
-    "version": "2.4.3",
+    "version": "2.4.5",
     "description": "A package for creating Distributed Validators using the Obol API.",
     "bugs": {
         "url": "https://github.com/obolnetwork/obol-sdk/issues"
@@ -23,7 +23,8 @@
         "lint": "eslint \"{src,test}/**/*.{js,ts}\" --fix",
         "lint-ci": "eslint \"{src,test}/**/*.{js,ts}\"",
         "prettier-ci": "prettier --check \"{src,test}/**/*.{js,ts}\"",
-        "prettier": "prettier --write \"{src,test}/**/*.{js,ts}\""
+        "prettier": "prettier --write \"{src,test}/**/*.{js,ts}\"",
+        "docs": "typedoc"
     },
     "main": "./dist/cjs/src/index.js",
     "module": "./dist/esm/src/index.js",
@@ -79,8 +80,8 @@
         "release-it": "^17.2.1",
         "ts-jest": "^28.0.8",
         "tsup": "^6.7.0",
-        "typedoc": "^0.25.7",
-        "typedoc-plugin-markdown": "^4.0.0-next.50",
+        "typedoc": "^0.28.0",
+        "typedoc-plugin-markdown": "^4.5.2",
         "typescript": "~5.3.3"
     },
     "engines": {

package/dist/esm/src/{incentivesHalpers.js → incentiveHelpers.js}

@@ -7,7 +7,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import { Contract, } from 'ethers';
+import { Contract } from 'ethers';
 import { MerkleDistributorABI } from './abi/MerkleDistributorWithDeadline';
 import { getProvider } from './utils';
 export const claimIncentivesFromMerkleDistributor = (incentivesData) => __awaiter(void 0, void 0, void 0, function* () {

package/dist/esm/src/incentives.js

@@ -9,8 +9,16 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 import { isContractAvailable } from './utils';
 import { FORK_NAMES, } from './types';
-import { claimIncentivesFromMerkleDistributor, isClaimedFromMerkleDistributor, } from './incentivesHalpers';
+import { claimIncentivesFromMerkleDistributor, isClaimedFromMerkleDistributor, } from './incentiveHelpers';
 import { DEFAULT_BASE_VERSION } from './constants';
+/**
+ * Incentives can be used for fetching and claiming Obol incentives.
+ * @class
+ * @internal Access it through Client.incentives.
+ * @example
+ * const obolClient = new Client(config);
+ * await obolClient.incentives.claimIncentives(address);
+ */
 export class Incentives {
     constructor(signer, chainId, request, provider) {
         this.signer = signer;
@@ -19,39 +27,49 @@ export class Incentives {
         this.provider = provider;
     }
     /**
-     * Claims obol incentives from a Merkle Distributor contract.
+     * Claims Obol incentives from a Merkle Distributor contract using an address.
+     *
+     * This method automatically fetches incentive data and verifies whether the incentives have already been claimed.
+     * If `txHash` is `null`, it indicates that the incentives were already claimed.
+     *
+     * Note: This method is not yet enabled and will throw an error if called.
      *
      * @remarks
      * **⚠️ Important:**  If you're storing the private key in an `.env` file, ensure it is securely managed
      * and not pushed to version control.
      *
-     * @param {Object} incentivesData - The incentives data needed for claiming.
-     * @param {string} incentivesData.contractAddress - The address of the Merkle Distributor contract.
-     * @param {number} incentivesData.index - The index in the Merkle tree.
-     * @param {string} incentivesData.operatorAddress - The address of the operator.
-     * @param {number} incentivesData.amount - The amount to claim.
-     * @param {string[]} incentivesData.merkleProof - The Merkle proof.
-     * @returns {Promise<{ txHash: string }>} The transaction hash of the claim transaction.
-     * @throws Will throw an error if the contract is not available or the claim fails.
+     * @param {string} address - The address to claim incentives for
+     * @returns {Promise<ClaimIncentivesResponse>} The transaction hash or already claimed status
+     * @throws Will throw an error if the incentives data is not found or the claim fails
      *
+     * An example of how to use claimIncentives:
+     * [obolClient](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L281)
      */
-    claimIncentives(incentivesData) {
+    claimIncentives(address) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this.signer) {
                 throw new Error('Signer is required in claimIncentives');
             }
             try {
-                const isContractDeployed = yield isContractAvailable(incentivesData.contractAddress, this.signer.provider);
+                const incentivesData = yield this.getIncentivesByAddress(address);
+                if (!(incentivesData === null || incentivesData === void 0 ? void 0 : incentivesData.contract_address)) {
+                    throw new Error(`No incentives found for address ${address}`);
+                }
+                const isContractDeployed = yield isContractAvailable(incentivesData.contract_address, this.provider);
                 if (!isContractDeployed) {
-                    throw new Error(`Merkle Distributor contract is not available at address ${incentivesData.contractAddress}`);
+                    throw new Error(`Merkle Distributor contract is not available at address ${incentivesData.contract_address}`);
+                }
+                const claimed = yield this.isClaimed(incentivesData.contract_address, incentivesData.index);
+                if (claimed) {
+                    return { txHash: null };
                 }
                 const { txHash } = yield claimIncentivesFromMerkleDistributor({
                     signer: this.signer,
-                    contractAddress: incentivesData.contractAddress,
+                    contractAddress: incentivesData.contract_address,
                     index: incentivesData.index,
-                    operatorAddress: incentivesData.operatorAddress,
+                    operatorAddress: incentivesData.operator_address,
                     amount: incentivesData.amount,
-                    merkleProof: incentivesData.merkleProof,
+                    merkleProof: incentivesData.merkle_proof,
                 });
                 return { txHash };
             }
@@ -68,6 +86,9 @@ export class Incentives {
      * @param {ETH_ADDRESS} index - operator index in merkle tree
      * @returns {Promise<boolean>} true if incentives are already claime
      *
+     *
+     * An example of how to use isClaimed:
+     * [obolClient](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L266)
      */
     isClaimed(contractAddress, index) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -78,6 +99,9 @@ export class Incentives {
      * @param address - Operator address
      * @returns {Promise<IncentivesType>} The matched incentives from DB
      * @throws On not found if address not found.
+     *
+     * An example of how to use getIncentivesByAddress:
+     * [obolClient](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L250)
      */
     getIncentivesByAddress(address) {
         return __awaiter(this, void 0, void 0, function* () {

package/dist/esm/src/index.js

@@ -7,7 +7,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import { ZeroAddress, } from 'ethers';
+import { ZeroAddress } from 'ethers';
 import { v4 as uuidv4 } from 'uuid';
 import { Base } from './base.js';
 import { CONFLICT_ERROR_MSG, CreatorConfigHashSigningTypes, Domain, DKG_ALGORITHM, CONFIG_VERSION, OperatorConfigHashSigningTypes, EnrSigningTypes, TERMS_AND_CONDITIONS_VERSION, TermsAndConditionsSigningTypes, DEFAULT_BASE_VERSION, TERMS_AND_CONDITIONS_HASH, AVAILABLE_SPLITTER_CHAINS, CHAIN_CONFIGURATION, DEFAULT_RETROACTIVE_FUNDING_REWARDS_ONLY_SPLIT, DEFAULT_RETROACTIVE_FUNDING_TOTAL_SPLIT, OBOL_SDK_EMAIL, } from './constants.js';
@@ -22,6 +22,7 @@ export * from './types.js';
 export * from './services.js';
 export * from './verification/signature-validator.js';
 export * from './verification/common.js';
+export { Incentives } from './incentives.js';
 /**
  * Obol sdk Client can be used for creating, managing and activating distributed validators.
  */
@@ -42,7 +43,7 @@ export class Client extends Base {
         // Use the provided provider, or fall back to signer.provider if available
         this.provider =
             provider !== null && provider !== void 0 ? provider : (signer && 'provider' in signer ? signer.provider : undefined);
-        this.incentives = new Incentives(this.signer, this.chainId, this.request.bind(this), (this.provider = provider));
+        this.incentives = new Incentives(this.signer, this.chainId, this.request.bind(this), this.provider);
     }
     /**
      * Accepts Obol terms and conditions to be able to create or update data.

package/dist/esm/src/splitHelpers.js

@@ -7,7 +7,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import { Contract, Interface, parseEther, ZeroAddress, } from 'ethers';
+import { Contract, Interface, parseEther, ZeroAddress } from 'ethers';
 import { OWRContract, OWRFactoryContract } from './abi/OWR';
 import { splitMainEthereumAbi } from './abi/SplitMain';
 import { MultiCallContract } from './abi/Multicall';

package/dist/esm/src/types.js

@@ -16,20 +16,11 @@ export var FORK_MAPPING;
     /** Hoodi Chain. */
     FORK_MAPPING[FORK_MAPPING["0x10000910"] = 560048] = "0x10000910";
 })(FORK_MAPPING || (FORK_MAPPING = {}));
-/**
- * Permitted Chain Names
- */
 export const FORK_NAMES = {
-    /** Mainnet. */
     [FORK_MAPPING['0x00000000']]: 'mainnet',
-    /** Goerli/Prater. */
     [FORK_MAPPING['0x00001020']]: 'goerli',
-    /** Gnosis Chain. */
     [FORK_MAPPING['0x00000064']]: 'gnosis',
-    /** Holesky. */
     [FORK_MAPPING['0x01017000']]: 'holesky',
-    /** Sepolia. */
     [FORK_MAPPING['0x90000069']]: 'sepolia',
-    /** Hoodi. */
     [FORK_MAPPING['0x10000910']]: 'hoodi',
 };