Merge branch 'develop' into contracts-v2

Author: flopez7

.changeset/olive-ideas-carry.md

@@ -1,3 +1,4 @@
-root: ./docs
+root: ./docs/sdk
 structure:
-  summary: SUMMARY.md
+  readme: README.md
+  summary: SUMMARY.md

.gitbook.yaml

@@ -0,0 +1,29 @@
+name: Publish SDK Docs to GitBook
+
+on:
+  push:
+    tags:
+      - "sdk@*"
+
+permissions:
+  contents: read
+
+jobs:
+  publish-docs:
+    name: Sync docs to GitBook
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+      - name: Publish docs
+        env:
+          GITBOOK_API_TOKEN: ${{ secrets.GITBOOK_API_TOKEN }}
+          GITBOOK_ORG_ID: ${{ secrets.GITBOOK_ORG_ID }}
+          PARENT_SPACE_ID: ${{ secrets.GITBOOK_PARENT_SPACE_ID }}
+          GITBOOK_SITE_ID: ${{ secrets.GITBOOK_SITE_ID }}
+          GIT_REF: ${{ github.ref }}
+          SPACE_VISIBILITY: ${{ vars.GITBOOK_SPACE_VISIBILITY }}
+          MAKE_DEFAULT: ${{ vars.GITBOOK_MAKE_DEFAULT }}
+        run: node scripts/gitbook-sync-sdk.mjs

.github/workflows/cd-gitbook-sdk-docs.yaml

@@ -14,6 +14,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
+        with:
+          token: ${{ secrets.GH_GITBOOK_TOKEN }}
       - uses: actions/setup-node@v4
         with:
           node-version-file: .nvmrc

.github/workflows/cd-packages.yaml

@@ -0,0 +1,38 @@
+# HUMAN Protocol SDK
+
+Welcome to the official documentation for HUMAN Protocol SDK.
+
+## Overview
+
+- Covers both TypeScript and Python SDKs used to build on HUMAN Protocol.
+- Use the sidebar to browse guides and API references; search to quickly find classes and functions.
+
+## Install
+
+### Typescript
+
+```bash
+npm install @human-protocol/sdk
+# or
+yarn add @human-protocol/sdk
+```
+
+### Python
+
+```bash
+pip install human-protocol-sdk
+```
+
+## Links
+
+- [NPM package](https://www.npmjs.com/package/@human-protocol/sdk)
+- [PyPI package](https://pypi.org/project/human-protocol-sdk/)
+- [GitHub repository](https://github.com/humanprotocol/human-protocol)
+
+## Versioning
+
+- Content is imported from the repository at release time.
+
+## Changelog
+
+- [CHANGELOG](changelog.md) — release notes and changes.

docs/sdk/README.md

@@ -1,5 +1,7 @@
 # Table of contents
 
+- [HUMAN Protocol SDK](README.md)
+
 ## Typescript SDK
 
 - [Encryption](typescript/encryption/README.md)

docs/sdk/SUMMARY.md

@@ -4,6 +4,9 @@
 
 ### Changed
 
+- Relaxed several SDK return types (EscrowUtils, OperatorUtils, TransactionUtils, WorkerUtils) to allow `null` when a subgraph entity does not exist.
+- EscrowUtils.getEscrow now includes `chainId` in the returned object.
+
 ### Deprecated
 
 ### Removed

docs/sdk/changelog.md

@@ -6,7 +6,7 @@
 
 # Abstract Class: BaseEthersClient
 
-Defined in: [base.ts:12](https://github.com/humanprotocol/human-protocol/blob/111a3dfb8ed775487998fa7cc407fdc884e7a927/packages/sdk/typescript/human-protocol-sdk/src/base.ts#L12)
+Defined in: [base.ts:12](https://github.com/humanprotocol/human-protocol/blob/c6ab6b31903af39ac6b3e92bd60cecc017b01413/packages/sdk/typescript/human-protocol-sdk/src/base.ts#L12)
 
 ## 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`
 
-Defined in: [base.ts:22](https://github.com/humanprotocol/human-protocol/blob/111a3dfb8ed775487998fa7cc407fdc884e7a927/packages/sdk/typescript/human-protocol-sdk/src/base.ts#L22)
+Defined in: [base.ts:22](https://github.com/humanprotocol/human-protocol/blob/c6ab6b31903af39ac6b3e92bd60cecc017b01413/packages/sdk/typescript/human-protocol-sdk/src/base.ts#L22)
 
 **BaseClient constructor**
 
@@ -52,23 +52,23 @@ The network information required to connect to the contracts
 
 > **networkData**: [`NetworkData`](../../types/type-aliases/NetworkData.md)
 
-Defined in: [base.ts:14](https://github.com/humanprotocol/human-protocol/blob/111a3dfb8ed775487998fa7cc407fdc884e7a927/packages/sdk/typescript/human-protocol-sdk/src/base.ts#L14)
+Defined in: [base.ts:14](https://github.com/humanprotocol/human-protocol/blob/c6ab6b31903af39ac6b3e92bd60cecc017b01413/packages/sdk/typescript/human-protocol-sdk/src/base.ts#L14)
 
 ***
 
 ### runner
 
 > `protected` **runner**: `ContractRunner`
 
-Defined in: [base.ts:13](https://github.com/humanprotocol/human-protocol/blob/111a3dfb8ed775487998fa7cc407fdc884e7a927/packages/sdk/typescript/human-protocol-sdk/src/base.ts#L13)
+Defined in: [base.ts:13](https://github.com/humanprotocol/human-protocol/blob/c6ab6b31903af39ac6b3e92bd60cecc017b01413/packages/sdk/typescript/human-protocol-sdk/src/base.ts#L13)
 
 ## Methods
 
 ### applyTxDefaults()
 
 > `protected` **applyTxDefaults**(`txOptions`): `Overrides`
 
-Defined in: [base.ts:35](https://github.com/humanprotocol/human-protocol/blob/111a3dfb8ed775487998fa7cc407fdc884e7a927/packages/sdk/typescript/human-protocol-sdk/src/base.ts#L35)
+Defined in: [base.ts:35](https://github.com/humanprotocol/human-protocol/blob/c6ab6b31903af39ac6b3e92bd60cecc017b01413/packages/sdk/typescript/human-protocol-sdk/src/base.ts#L35)
 
 Internal helper to enrich transaction overrides with network specific defaults.
 

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

@@ -6,7 +6,7 @@
 
 # Class: Encryption
 
-Defined in: [encryption.ts:58](https://github.com/humanprotocol/human-protocol/blob/111a3dfb8ed775487998fa7cc407fdc884e7a927/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L58)
+Defined in: [encryption.ts:58](https://github.com/humanprotocol/human-protocol/blob/c6ab6b31903af39ac6b3e92bd60cecc017b01413/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`
 
-Defined in: [encryption.ts:66](https://github.com/humanprotocol/human-protocol/blob/111a3dfb8ed775487998fa7cc407fdc884e7a927/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L66)
+Defined in: [encryption.ts:66](https://github.com/humanprotocol/human-protocol/blob/c6ab6b31903af39ac6b3e92bd60cecc017b01413/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/111a3dfb8ed775487998fa7cc407fdc884e7a927/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L194)
+Defined in: [encryption.ts:194](https://github.com/humanprotocol/human-protocol/blob/c6ab6b31903af39ac6b3e92bd60cecc017b01413/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/111a3dfb8ed775487998fa7cc407fdc884e7a927/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L251)
+Defined in: [encryption.ts:251](https://github.com/humanprotocol/human-protocol/blob/c6ab6b31903af39ac6b3e92bd60cecc017b01413/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/111a3dfb8ed775487998fa7cc407fdc884e7a927/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L142)
+Defined in: [encryption.ts:142](https://github.com/humanprotocol/human-protocol/blob/c6ab6b31903af39ac6b3e92bd60cecc017b01413/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`\>
 
-Defined in: [encryption.ts:77](https://github.com/humanprotocol/human-protocol/blob/111a3dfb8ed775487998fa7cc407fdc884e7a927/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L77)
+Defined in: [encryption.ts:77](https://github.com/humanprotocol/human-protocol/blob/c6ab6b31903af39ac6b3e92bd60cecc017b01413/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/Encryption.md

@@ -6,7 +6,7 @@
 
 # Class: EncryptionUtils
 
-Defined in: [encryption.ts:290](https://github.com/humanprotocol/human-protocol/blob/111a3dfb8ed775487998fa7cc407fdc884e7a927/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L290)
+Defined in: [encryption.ts:290](https://github.com/humanprotocol/human-protocol/blob/c6ab6b31903af39ac6b3e92bd60cecc017b01413/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L290)
 
 ## Introduction
 
@@ -48,7 +48,7 @@ const keyPair = await EncryptionUtils.generateKeyPair('Human', '[email protected]');
 
 > `static` **encrypt**(`message`, `publicKeys`): `Promise`\<`string`\>
 
-Defined in: [encryption.ts:444](https://github.com/humanprotocol/human-protocol/blob/111a3dfb8ed775487998fa7cc407fdc884e7a927/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L444)
+Defined in: [encryption.ts:444](https://github.com/humanprotocol/human-protocol/blob/c6ab6b31903af39ac6b3e92bd60cecc017b01413/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/111a3dfb8ed775487998fa7cc407fdc884e7a927/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L382)
+Defined in: [encryption.ts:382](https://github.com/humanprotocol/human-protocol/blob/c6ab6b31903af39ac6b3e92bd60cecc017b01413/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/111a3dfb8ed775487998fa7cc407fdc884e7a927/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L351)
+Defined in: [encryption.ts:351](https://github.com/humanprotocol/human-protocol/blob/c6ab6b31903af39ac6b3e92bd60cecc017b01413/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/111a3dfb8ed775487998fa7cc407fdc884e7a927/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L494)
+Defined in: [encryption.ts:494](https://github.com/humanprotocol/human-protocol/blob/c6ab6b31903af39ac6b3e92bd60cecc017b01413/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/111a3dfb8ed775487998fa7cc407fdc884e7a927/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L318)
+Defined in: [encryption.ts:318](https://github.com/humanprotocol/human-protocol/blob/c6ab6b31903af39ac6b3e92bd60cecc017b01413/packages/sdk/typescript/human-protocol-sdk/src/encryption.ts#L318)
 
 This function verifies the signature of a signed message using the public key.