feat: Enhance payout and status event filtering in the Human Protocol SDK

docs/sdk/python/human_protocol_sdk.escrow.escrow_utils.md

@@ -108,45 +108,48 @@ Get an array of escrow addresses based on the specified filter parameters.
   )
   ```
 
-#### *static* get_status_events(chain_id, statuses=None, date_from=None, date_to=None, launcher=None, first=10, skip=0, order_direction=OrderDirection.DESC)
+#### *static* get_payouts(filter)
+
+Fetch payouts from the subgraph based on the provided filter.
+
+* **Parameters:**
+  **filter** ([`PayoutFilter`](human_protocol_sdk.filter.md#human_protocol_sdk.filter.PayoutFilter)) – Object containing all the necessary parameters to filter payouts.
+* **Return List[Payout]:**
+  List of payouts matching the query parameters.
+* **Raises:**
+  [**EscrowClientError**](human_protocol_sdk.escrow.escrow_client.md#human_protocol_sdk.escrow.escrow_client.EscrowClientError) – If an unsupported chain ID or invalid addresses are provided.
+* **Return type:**
+  `List`[[`Payout`](#human_protocol_sdk.escrow.escrow_utils.Payout)]
+
+#### *static* get_status_events(filter)
 
 Retrieve status events for specified networks and statuses within a date range.
 
 * **Parameters:**
-  * **chain_id** ([`ChainId`](human_protocol_sdk.constants.md#human_protocol_sdk.constants.ChainId)) – Network to request data.
-  * **(****Optional****[****List****[****Status****]****]****)** (*statuses*) – List of statuses to filter by.
-  * **(****Optional****[****datetime****]****)** (*date_to*) – Start date for the query range.
-  * **(****Optional****[****datetime****]****)** – End date for the query range.
-  * **(****Optional****[****str****]****)** (*launcher*) – Address of the launcher to filter by.
-  * **(****int****)** (*skip*) – Number of items per page.
-  * **(****int****)** – Page number to retrieve.
-  * **(****OrderDirection****)** (*order_direction*) – Order of results, “asc” or “desc”.
+  **filter** ([`StatusEventFilter`](human_protocol_sdk.filter.md#human_protocol_sdk.filter.StatusEventFilter)) – Object containing all the necessary parameters to filter status events.
 * **Return List[StatusEvent]:**
   List of status events matching the query parameters.
 * **Raises:**
   [**EscrowClientError**](human_protocol_sdk.escrow.escrow_client.md#human_protocol_sdk.escrow.escrow_client.EscrowClientError) – If an unsupported chain ID or invalid launcher address is provided.
-* **Example:**
-  ```python
-  from datetime import datetime
-  from human_protocol_sdk.constants import ChainId, Status
-  from human_protocol_sdk.escrow import EscrowUtils
-
-  print(
-      EscrowUtils.get_status_events(
-          chain_id=ChainId.POLYGON_AMOY,
-          statuses=[Status.Pending, Status.Paid],
-          date_from=datetime(2023, 1, 1),
-          date_to=datetime(2023, 12, 31),
-          launcher="0x1234567890abcdef1234567890abcdef12345678",
-          first=20,
-          skip=0,
-          order_direction=OrderDirection.DESC
-      )
-  )
-  ```
 * **Return type:**
   `List`[[`StatusEvent`](#human_protocol_sdk.escrow.escrow_utils.StatusEvent)]
 
+### *class* human_protocol_sdk.escrow.escrow_utils.Payout(id, escrow_address, recipient, amount, created_at)
+
+Bases: `object`
+
+Initializes a Payout instance.
+
+* **Parameters:**
+  * **id** (`str`) – The id of the payout.
+  * **chain_id** – The chain identifier where the payout occurred.
+  * **escrow_address** (`str`) – The address of the escrow that executed the payout.
+  * **recipient** (`str`) – The address of the recipient.
+  * **amount** (`int`) – The amount of the payout.
+  * **created_at** (`int`) – The time of creation of the payout.
+
+#### \_\_init_\_(id, escrow_address, recipient, amount, created_at)
+
 ### *class* human_protocol_sdk.escrow.escrow_utils.StatusEvent(timestamp, status, chain_id, escrow_address)
 
 Bases: `object`

docs/sdk/python/human_protocol_sdk.escrow.md

@@ -48,6 +48,9 @@ obtain information from both the contracts and subgraph.
   * [`EscrowUtils`](human_protocol_sdk.escrow.escrow_utils.md#human_protocol_sdk.escrow.escrow_utils.EscrowUtils)
     * [`EscrowUtils.get_escrow()`](human_protocol_sdk.escrow.escrow_utils.md#human_protocol_sdk.escrow.escrow_utils.EscrowUtils.get_escrow)
     * [`EscrowUtils.get_escrows()`](human_protocol_sdk.escrow.escrow_utils.md#human_protocol_sdk.escrow.escrow_utils.EscrowUtils.get_escrows)
+    * [`EscrowUtils.get_payouts()`](human_protocol_sdk.escrow.escrow_utils.md#human_protocol_sdk.escrow.escrow_utils.EscrowUtils.get_payouts)
     * [`EscrowUtils.get_status_events()`](human_protocol_sdk.escrow.escrow_utils.md#human_protocol_sdk.escrow.escrow_utils.EscrowUtils.get_status_events)
+  * [`Payout`](human_protocol_sdk.escrow.escrow_utils.md#human_protocol_sdk.escrow.escrow_utils.Payout)
+    * [`Payout.__init__()`](human_protocol_sdk.escrow.escrow_utils.md#human_protocol_sdk.escrow.escrow_utils.Payout.__init__)
   * [`StatusEvent`](human_protocol_sdk.escrow.escrow_utils.md#human_protocol_sdk.escrow.escrow_utils.StatusEvent)
     * [`StatusEvent.__init__()`](human_protocol_sdk.escrow.escrow_utils.md#human_protocol_sdk.escrow.escrow_utils.StatusEvent.__init__)

docs/sdk/python/human_protocol_sdk.filter.md

@@ -30,21 +30,25 @@ Bases: `Exception`
 
 Raises when some error happens when building filter object.
 
-### *class* human_protocol_sdk.filter.PayoutFilter(escrow_address=None, recipient=None, date_from=None, date_to=None)
+### *class* human_protocol_sdk.filter.PayoutFilter(chain_id, escrow_address=None, recipient=None, date_from=None, date_to=None, first=10, skip=0, order_direction=OrderDirection.DESC)
 
 Bases: `object`
 
 A class used to filter payout requests.
 
-#### \_\_init_\_(escrow_address=None, recipient=None, date_from=None, date_to=None)
+#### \_\_init_\_(chain_id, escrow_address=None, recipient=None, date_from=None, date_to=None, first=10, skip=0, order_direction=OrderDirection.DESC)
 
-Initializes a PayoutFilter instance.
+Initializes a filter for payouts.
 
 * **Parameters:**
-  * **escrow_address** (`Optional`[`str`]) – Escrow address
-  * **recipient** (`Optional`[`str`]) – Recipient address
-  * **date_from** (`Optional`[`datetime`]) – Created from date
-  * **date_to** (`Optional`[`datetime`]) – Created to date
+  * **chain_id** ([`ChainId`](human_protocol_sdk.constants.md#human_protocol_sdk.constants.ChainId)) – The chain ID where the payouts are recorded.
+  * **escrow_address** (`Optional`[`str`]) – Optional escrow address to filter payouts.
+  * **recipient** (`Optional`[`str`]) – Optional recipient address to filter payouts.
+  * **date_from** (`Optional`[`datetime`]) – Optional start date for filtering.
+  * **date_to** (`Optional`[`datetime`]) – Optional end date for filtering.
+  * **first** (`int`) – Optional number of payouts per page. Default is 10.
+  * **skip** (`int`) – Optional number of payouts to skip. Default is 0.
+  * **order_direction** ([`OrderDirection`](human_protocol_sdk.constants.md#human_protocol_sdk.constants.OrderDirection)) – Optional order direction. Default is DESC.
 
 ### *class* human_protocol_sdk.filter.StatisticsFilter(date_from=None, date_to=None, first=10, skip=0, order_direction=OrderDirection.ASC)
 
@@ -74,6 +78,24 @@ A class used to filter statistical data.
 
 #### \_\_init_\_(date_from=None, date_to=None, first=10, skip=0, order_direction=OrderDirection.ASC)
 
+### *class* human_protocol_sdk.filter.StatusEventFilter(chain_id, statuses=None, date_from=None, date_to=None, launcher=None, first=10, skip=0, order_direction=OrderDirection.DESC)
+
+Bases: `object`
+
+#### \_\_init_\_(chain_id, statuses=None, date_from=None, date_to=None, launcher=None, first=10, skip=0, order_direction=OrderDirection.DESC)
+
+Initializes a filter for status events.
+
+* **Parameters:**
+  * **chain_id** ([`ChainId`](human_protocol_sdk.constants.md#human_protocol_sdk.constants.ChainId)) – The chain ID where the events are recorded.
+  * **statuses** (`Optional`[`List`[[`Status`](human_protocol_sdk.constants.md#human_protocol_sdk.constants.Status)]]) – Optional list of statuses to filter by.
+  * **date_from** (`Optional`[`datetime`]) – Optional start date for filtering.
+  * **date_to** (`Optional`[`datetime`]) – Optional end date for filtering.
+  * **launcher** (`Optional`[`str`]) – Optional launcher address to filter by.
+  * **first** (`int`) – Optional number of events per page. Default is 10.
+  * **skip** (`int`) – Optional number of events to skip. Default is 0.
+  * **order_direction** ([`OrderDirection`](human_protocol_sdk.constants.md#human_protocol_sdk.constants.OrderDirection)) – Optional order direction. Default is DESC.
+
 ### *class* human_protocol_sdk.filter.TransactionFilter(chain_id, from_address=None, to_address=None, start_date=None, end_date=None, start_block=None, end_block=None, first=10, skip=0, order_direction=OrderDirection.DESC)
 
 Bases: `object`

docs/sdk/python/human_protocol_sdk.legacy_encryption.md

@@ -17,7 +17,7 @@ Encryption class specialized in encrypting and decrypting a byte string.
 
 #### CIPHER
 
-Cipher algorithm defintion.
+Cipher algorithm definition.
 
 alias of `AES`
 

docs/sdk/python/human_protocol_sdk.md

@@ -46,6 +46,7 @@
       * [Module](human_protocol_sdk.escrow.escrow_utils.md#module)
       * [`EscrowData`](human_protocol_sdk.escrow.escrow_utils.md#human_protocol_sdk.escrow.escrow_utils.EscrowData)
       * [`EscrowUtils`](human_protocol_sdk.escrow.escrow_utils.md#human_protocol_sdk.escrow.escrow_utils.EscrowUtils)
+      * [`Payout`](human_protocol_sdk.escrow.escrow_utils.md#human_protocol_sdk.escrow.escrow_utils.Payout)
       * [`StatusEvent`](human_protocol_sdk.escrow.escrow_utils.md#human_protocol_sdk.escrow.escrow_utils.StatusEvent)
 * [human_protocol_sdk.kvstore package](human_protocol_sdk.kvstore.md)
   * [Submodules](human_protocol_sdk.kvstore.md#submodules)
@@ -164,6 +165,8 @@
     * [`PayoutFilter.__init__()`](human_protocol_sdk.filter.md#human_protocol_sdk.filter.PayoutFilter.__init__)
   * [`StatisticsFilter`](human_protocol_sdk.filter.md#human_protocol_sdk.filter.StatisticsFilter)
     * [`StatisticsFilter.__init__()`](human_protocol_sdk.filter.md#human_protocol_sdk.filter.StatisticsFilter.__init__)
+  * [`StatusEventFilter`](human_protocol_sdk.filter.md#human_protocol_sdk.filter.StatusEventFilter)
+    * [`StatusEventFilter.__init__()`](human_protocol_sdk.filter.md#human_protocol_sdk.filter.StatusEventFilter.__init__)
   * [`TransactionFilter`](human_protocol_sdk.filter.md#human_protocol_sdk.filter.TransactionFilter)
     * [`TransactionFilter.__init__()`](human_protocol_sdk.filter.md#human_protocol_sdk.filter.TransactionFilter.__init__)
 * [human_protocol_sdk.legacy_encryption module](human_protocol_sdk.legacy_encryption.md)

docs/sdk/python/index.md

@@ -55,6 +55,7 @@ pip install human-protocol-sdk[agreement]
       * [`FilterError`](human_protocol_sdk.filter.md#human_protocol_sdk.filter.FilterError)
       * [`PayoutFilter`](human_protocol_sdk.filter.md#human_protocol_sdk.filter.PayoutFilter)
       * [`StatisticsFilter`](human_protocol_sdk.filter.md#human_protocol_sdk.filter.StatisticsFilter)
+      * [`StatusEventFilter`](human_protocol_sdk.filter.md#human_protocol_sdk.filter.StatusEventFilter)
       * [`TransactionFilter`](human_protocol_sdk.filter.md#human_protocol_sdk.filter.TransactionFilter)
     * [human_protocol_sdk.legacy_encryption module](human_protocol_sdk.legacy_encryption.md)
       * [`DecryptionError`](human_protocol_sdk.legacy_encryption.md#human_protocol_sdk.legacy_encryption.DecryptionError)

docs/sdk/typescript/base/classes/BaseEthersClient.md

@@ -6,7 +6,7 @@
 
 # Class: `abstract` BaseEthersClient
 
-Defined in: [base.ts:10](https://github.com/humanprotocol/human-protocol/blob/06afdec15d4185a13ccdd98fd231f6651db0e480/packages/sdk/typescript/human-protocol-sdk/src/base.ts#L10)
+Defined in: [base.ts:10](https://github.com/humanprotocol/human-protocol/blob/d770e8f228f083f5eba0523ebbdff361b3188c3d/packages/sdk/typescript/human-protocol-sdk/src/base.ts#L10)
 
 ## Introduction
 
@@ -24,7 +24,7 @@ This class is used as a base class for other clients making on-chain calls.
 
 > **new BaseEthersClient**(`runner`, `networkData`): [`BaseEthersClient`](BaseEthersClient.md)
 
-Defined in: [base.ts:20](https://github.com/humanprotocol/human-protocol/blob/06afdec15d4185a13ccdd98fd231f6651db0e480/packages/sdk/typescript/human-protocol-sdk/src/base.ts#L20)
+Defined in: [base.ts:20](https://github.com/humanprotocol/human-protocol/blob/d770e8f228f083f5eba0523ebbdff361b3188c3d/packages/sdk/typescript/human-protocol-sdk/src/base.ts#L20)
 
 **BaseClient constructor**
 
@@ -52,12 +52,12 @@ The network information required to connect to the contracts
 
 > **networkData**: [`NetworkData`](../../types/type-aliases/NetworkData.md)
 
-Defined in: [base.ts:12](https://github.com/humanprotocol/human-protocol/blob/06afdec15d4185a13ccdd98fd231f6651db0e480/packages/sdk/typescript/human-protocol-sdk/src/base.ts#L12)
+Defined in: [base.ts:12](https://github.com/humanprotocol/human-protocol/blob/d770e8f228f083f5eba0523ebbdff361b3188c3d/packages/sdk/typescript/human-protocol-sdk/src/base.ts#L12)
 
 ***
 
 ### runner
 
 > `protected` **runner**: `ContractRunner`
 
-Defined in: [base.ts:11](https://github.com/humanprotocol/human-protocol/blob/06afdec15d4185a13ccdd98fd231f6651db0e480/packages/sdk/typescript/human-protocol-sdk/src/base.ts#L11)
+Defined in: [base.ts:11](https://github.com/humanprotocol/human-protocol/blob/d770e8f228f083f5eba0523ebbdff361b3188c3d/packages/sdk/typescript/human-protocol-sdk/src/base.ts#L11)

docs/sdk/typescript/encryption/classes/Encryption.md

@@ -6,7 +6,7 @@
 
 # Class: Encryption
 
-Defined in: [encryption.ts:58](https://github.com/humanprotocol/human-protocol/blob/06afdec15d4185a13ccdd98fd231f6651db0e480/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L58)
+Defined in: [encryption.ts:58](https://github.com/humanprotocol/human-protocol/blob/d770e8f228f083f5eba0523ebbdff361b3188c3d/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L58)
 
 ## Introduction
 
@@ -53,7 +53,7 @@ const encryption = await Encryption.build(privateKey, passphrase);
 
 > **new Encryption**(`privateKey`): [`Encryption`](Encryption.md)
 
-Defined in: [encryption.ts:66](https://github.com/humanprotocol/human-protocol/blob/06afdec15d4185a13ccdd98fd231f6651db0e480/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L66)
+Defined in: [encryption.ts:66](https://github.com/humanprotocol/human-protocol/blob/d770e8f228f083f5eba0523ebbdff361b3188c3d/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L66)
 
 Constructor for the Encryption class.
 
@@ -75,7 +75,7 @@ The private key.
 
 > **decrypt**(`message`, `publicKey`?): `Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\>
 
-Defined in: [encryption.ts:194](https://github.com/humanprotocol/human-protocol/blob/06afdec15d4185a13ccdd98fd231f6651db0e480/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L194)
+Defined in: [encryption.ts:194](https://github.com/humanprotocol/human-protocol/blob/d770e8f228f083f5eba0523ebbdff361b3188c3d/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L194)
 
 This function decrypts messages using the private key. In addition, the public key can be added for signature verification.
 
@@ -129,7 +129,7 @@ const resultMessage = await encryption.decrypt('message');
 
 > **sign**(`message`): `Promise`\<`string`\>
 
-Defined in: [encryption.ts:251](https://github.com/humanprotocol/human-protocol/blob/06afdec15d4185a13ccdd98fd231f6651db0e480/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L251)
+Defined in: [encryption.ts:251](https://github.com/humanprotocol/human-protocol/blob/d770e8f228f083f5eba0523ebbdff361b3188c3d/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L251)
 
 This function signs a message using the private key used to initialize the client.
 
@@ -165,7 +165,7 @@ const resultMessage = await encryption.sign('message');
 
 > **signAndEncrypt**(`message`, `publicKeys`): `Promise`\<`string`\>
 
-Defined in: [encryption.ts:142](https://github.com/humanprotocol/human-protocol/blob/06afdec15d4185a13ccdd98fd231f6651db0e480/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L142)
+Defined in: [encryption.ts:142](https://github.com/humanprotocol/human-protocol/blob/d770e8f228f083f5eba0523ebbdff361b3188c3d/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L142)
 
 This function signs and encrypts a message using the private key used to initialize the client and the specified public keys.
 
@@ -232,7 +232,7 @@ const resultMessage = await encryption.signAndEncrypt('message', publicKeys);
 
 > `static` **build**(`privateKeyArmored`, `passphrase`?): `Promise`\<[`Encryption`](Encryption.md)\>
 
-Defined in: [encryption.ts:77](https://github.com/humanprotocol/human-protocol/blob/06afdec15d4185a13ccdd98fd231f6651db0e480/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L77)
+Defined in: [encryption.ts:77](https://github.com/humanprotocol/human-protocol/blob/d770e8f228f083f5eba0523ebbdff361b3188c3d/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L77)
 
 Builds an Encryption instance by decrypting the private key from an encrypted private key and passphrase.
 

docs/sdk/typescript/encryption/classes/EncryptionUtils.md

@@ -6,7 +6,7 @@
 
 # Class: EncryptionUtils
 
-Defined in: [encryption.ts:290](https://github.com/humanprotocol/human-protocol/blob/06afdec15d4185a13ccdd98fd231f6651db0e480/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L290)
+Defined in: [encryption.ts:290](https://github.com/humanprotocol/human-protocol/blob/d770e8f228f083f5eba0523ebbdff361b3188c3d/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L290)
 
 ## Introduction
 
@@ -48,7 +48,7 @@ const keyPair = await EncryptionUtils.generateKeyPair('Human', 'human@hmt.ai');
 
 > `static` **encrypt**(`message`, `publicKeys`): `Promise`\<`string`\>
 
-Defined in: [encryption.ts:444](https://github.com/humanprotocol/human-protocol/blob/06afdec15d4185a13ccdd98fd231f6651db0e480/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L444)
+Defined in: [encryption.ts:444](https://github.com/humanprotocol/human-protocol/blob/d770e8f228f083f5eba0523ebbdff361b3188c3d/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L444)
 
 This function encrypts a message using the specified public keys.
 
@@ -111,7 +111,7 @@ const result = await EncryptionUtils.encrypt('message', publicKeys);
 
 > `static` **generateKeyPair**(`name`, `email`, `passphrase`): `Promise`\<[`IKeyPair`](../../interfaces/interfaces/IKeyPair.md)\>
 
-Defined in: [encryption.ts:382](https://github.com/humanprotocol/human-protocol/blob/06afdec15d4185a13ccdd98fd231f6651db0e480/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L382)
+Defined in: [encryption.ts:382](https://github.com/humanprotocol/human-protocol/blob/d770e8f228f083f5eba0523ebbdff361b3188c3d/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L382)
 
 This function generates a key pair for encryption and decryption.
 
@@ -158,7 +158,7 @@ const result = await EncryptionUtils.generateKeyPair(name, email, passphrase);
 
 > `static` **getSignedData**(`message`): `Promise`\<`string`\>
 
-Defined in: [encryption.ts:351](https://github.com/humanprotocol/human-protocol/blob/06afdec15d4185a13ccdd98fd231f6651db0e480/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L351)
+Defined in: [encryption.ts:351](https://github.com/humanprotocol/human-protocol/blob/d770e8f228f083f5eba0523ebbdff361b3188c3d/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L351)
 
 This function gets signed data from a signed message.
 
@@ -190,7 +190,7 @@ const signedData = await EncryptionUtils.getSignedData('message');
 
 > `static` **isEncrypted**(`message`): `boolean`
 
-Defined in: [encryption.ts:494](https://github.com/humanprotocol/human-protocol/blob/06afdec15d4185a13ccdd98fd231f6651db0e480/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L494)
+Defined in: [encryption.ts:494](https://github.com/humanprotocol/human-protocol/blob/d770e8f228f083f5eba0523ebbdff361b3188c3d/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L494)
 
 Verifies if a message appears to be encrypted with OpenPGP.
 
@@ -238,7 +238,7 @@ if (isEncrypted) {
 
 > `static` **verify**(`message`, `publicKey`): `Promise`\<`boolean`\>
 
-Defined in: [encryption.ts:318](https://github.com/humanprotocol/human-protocol/blob/06afdec15d4185a13ccdd98fd231f6651db0e480/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L318)
+Defined in: [encryption.ts:318](https://github.com/humanprotocol/human-protocol/blob/d770e8f228f083f5eba0523ebbdff361b3188c3d/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L318)
 
 This function verifies the signature of a signed message using the public key.