diff --git a/CHANGELOG.MD b/CHANGELOG.MD index b967b18..ef87fbf 100644 --- a/CHANGELOG.MD +++ b/CHANGELOG.MD @@ -9,7 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added -- methods for querying governance DReps endpoints - `dreps`, `drepsById`, `drepsByIdDelegators`, `drepsByIdDelegatorsAll`, `drepsByIdMetadata`, `drepsByIdUpdates`, `drepsByIdUpdatesAll`, `drepsByIdVotes`, `drepsByIdVotesAll` +- methods for querying [governance](https://docs.blockfrost.io/#tag/cardano--governance) DReps endpoints - `dreps`, `drepsById`, `drepsByIdDelegators`, `drepsByIdDelegatorsAll`, `drepsByIdMetadata`, `drepsByIdUpdates`, `drepsByIdUpdatesAll`, `drepsByIdVotes`, `drepsByIdVotesAll` +- methods for querying [governance](https://docs.blockfrost.io/#tag/cardano--governance) proposals endpoints - `proposals`, `proposal`, `proposalMetadata`, `proposalParameters`, `proposalVotes`, `proposalVotesAll`, `proposalWithdrawals`, `proposalWithdrawalsAll`, ## [5.6.0] - 2024-10-03 diff --git a/src/BlockFrostAPI.ts b/src/BlockFrostAPI.ts index 679d81e..e181f8a 100644 --- a/src/BlockFrostAPI.ts +++ b/src/BlockFrostAPI.ts @@ -71,6 +71,18 @@ import { drepsByIdVotes, drepsByIdVotesAll, } from './endpoints/api/governance/dreps'; + +import { + proposals, + proposal, + proposalMetadata, + proposalParameters, + proposalVotes, + proposalVotesAll, + proposalWithdrawals, + proposalWithdrawalsAll, +} from './endpoints/api/governance/proposals'; + import { epochs, epochsBlocks, @@ -331,6 +343,15 @@ class BlockFrostAPI { poolsExtended = poolsExtended; poolsExtendedAll = poolsExtendedAll; + proposals = proposals; + proposal = proposal; + proposalMetadata = proposalMetadata; + proposalParameters = proposalParameters; + proposalVotes = proposalVotes; + proposalVotesAll = proposalVotesAll; + proposalWithdrawals = proposalWithdrawals; + proposalWithdrawalsAll = proposalWithdrawalsAll; + root = root; scripts = scripts; diff --git a/src/endpoints/api/governance/dreps/index.ts b/src/endpoints/api/governance/dreps/index.ts index d8e1744..845ac91 100644 --- a/src/endpoints/api/governance/dreps/index.ts +++ b/src/endpoints/api/governance/dreps/index.ts @@ -6,7 +6,7 @@ import { handleError } from '../../../../utils/errors'; /** * Obtains list of Delegate Representatives (DReps). - * @see {@link https://docs.blockfrost.io/#tag/cardano--governance/GET/governance/dreps | API docs for of Delegate Representatives (DReps)} + * @see {@link https://docs.blockfrost.io/#tag/cardano--governance/GET/governance/dreps | API docs for Delegate Representatives (DReps)} * * @param pagination - Optional, Pagination options * @returns List of registered stake pools. diff --git a/src/endpoints/api/governance/proposals/index.ts b/src/endpoints/api/governance/proposals/index.ts new file mode 100644 index 0000000..b0568c6 --- /dev/null +++ b/src/endpoints/api/governance/proposals/index.ts @@ -0,0 +1,223 @@ +import { getPaginationOptions, paginateMethod } from '../../../../utils'; +import { components } from '@blockfrost/openapi'; +import { BlockFrostAPI } from '../../../../index'; +import { AllMethodOptions, PaginationOptions } from '../../../../types'; +import { handleError } from '../../../../utils/errors'; + +/** + * Obtains list of proposals. + * @see {@link https://docs.blockfrost.io/#tag/cardano--governance/GET/governance/proposals | API docs for Proposals} + * + * @param pagination - Optional, Pagination options + * @returns List of proposals + * + */ +export async function proposals( + this: BlockFrostAPI, + pagination?: PaginationOptions, +): Promise { + const paginationOptions = getPaginationOptions(pagination); + + try { + const res = await this.instance( + `governance/proposals`, + { + searchParams: { + page: paginationOptions.page, + count: paginationOptions.count, + order: paginationOptions.order, + }, + }, + ); + return res.body; + } catch (error) { + throw handleError(error); + } +} + +/** + * Obtains a specific Proposal + * @see {@link https://docs.blockfrost.io/#tag/cardano--governance/GET/governance/proposals/%tx_hash%7D/%cert_index%7D | API docs for Specific Proposal} + * + * @param txHash - Transaction Hash + * @param cert_index - Index of the certificate within the proposal transaction. + * @returns Proposal information + * + */ +export async function proposal( + this: BlockFrostAPI, + txHash: string, + certIndex: number, +): Promise { + try { + const res = await this.instance( + `governance/proposals/${txHash}/${certIndex}`, + ); + return res.body; + } catch (error) { + throw handleError(error); + } +} + +/** + * Obtains a parameters of specific proposal + * @see {@link https://docs.blockfrost.io/#tag/cardano--governance/GET/governance/proposals/%tx_hash%7D/%cert_index%7D/parameters | API docs for Specific Proposal parameters} + * + * @param txHash - Transaction Hash + * @param cert_index - Index of the certificate within the proposal transaction. + * @returns Parameters proposal details. + * + */ +export async function proposalParameters( + this: BlockFrostAPI, + txHash: string, + certIndex: number, +): Promise { + try { + const res = await this.instance< + components['schemas']['proposal_parameters'] + >(`governance/proposals/${txHash}/${certIndex}/parameters`); + return res.body; + } catch (error) { + throw handleError(error); + } +} + +/** + * Obtains Specific withdrawals proposal + * @see {@link https://docs.blockfrost.io/#tag/cardano--governance/GET/governance/proposals/%tx_hash%7D/%cert_index%7D/withdrawals | API docs for Specific withdrawals proposal} + * + * @param txHash - Transaction Hash + * @param cert_index - Index of the certificate within the proposal transaction. + * @returns Parameters withdrawals details. + * + */ +export async function proposalWithdrawals( + this: BlockFrostAPI, + txHash: string, + certIndex: number, + pagination?: PaginationOptions, +): Promise { + const paginationOptions = getPaginationOptions(pagination); + + try { + const res = await this.instance< + components['schemas']['proposal_withdrawals'] + >(`governance/proposals/${txHash}/${certIndex}/withdrawals`, { + searchParams: { + page: paginationOptions.page, + count: paginationOptions.count, + order: paginationOptions.order, + }, + }); + return res.body; + } catch (error) { + throw handleError(error); + } +} + +/** + * Obtains Specific withdrawals proposal + * @see {@link https://docs.blockfrost.io/#tag/cardano--governance/GET/governance/proposals/%tx_hash%7D/%cert_index%7D/withdrawals | API docs for Specific withdrawals proposal} + * @remarks + * Variant of `proposalWithdrawals` method for fetching all pages with built-in requests batching + * + * @param txHash - Transaction Hash + * @param cert_index - Index of the certificate within the proposal transaction. + * @param allMethodOptions - Optional, Options for request batching + * @returns Parameters withdrawals details. + * + */ +export async function proposalWithdrawalsAll( + this: BlockFrostAPI, + txHash: string, + certIndex: number, + allMethodOptions?: AllMethodOptions, +): Promise { + return paginateMethod( + pagination => this.proposalWithdrawals(txHash, certIndex, pagination), + allMethodOptions, + ); +} + +/** + * Obtains History of Proposal votes. + * @see {@link https://docs.blockfrost.io/#tag/cardano--governance/GET/governance/proposals/%tx_hash%7D/%cert_index%7D/votes | API docs for Proposal votes​} + * + * @param txHash - Transaction Hash + * @param cert_index - Index of the certificate within the proposal transaction. + * @returns History of Proposal votes. + * + */ +export async function proposalVotes( + this: BlockFrostAPI, + txHash: string, + certIndex: number, + pagination?: PaginationOptions, +): Promise { + const paginationOptions = getPaginationOptions(pagination); + + try { + const res = await this.instance( + `governance/proposals/${txHash}/${certIndex}/votes`, + { + searchParams: { + page: paginationOptions.page, + count: paginationOptions.count, + order: paginationOptions.order, + }, + }, + ); + return res.body; + } catch (error) { + throw handleError(error); + } +} + +/** + * Obtains History of Proposal votes. + * @see {@link https://docs.blockfrost.io/#tag/cardano--governance/GET/governance/proposals/%tx_hash%7D/%cert_index%7D/votes | API docs for Proposal votes​} + * @remarks + * Variant of `proposalVotes` method for fetching all pages with built-in requests batching + * + * @param txHash - Transaction Hash + * @param cert_index - Index of the certificate within the proposal transaction. + * @param allMethodOptions - Optional, Options for request batching + * @returns History of DRep votes + * + */ +export async function proposalVotesAll( + this: BlockFrostAPI, + txHash: string, + certIndex: number, + allMethodOptions?: AllMethodOptions, +): Promise { + return paginateMethod( + pagination => this.proposalVotes(txHash, certIndex, pagination), + allMethodOptions, + ); +} + +/** + * Obtains Proposal metadata information. + * @see {@link https://docs.blockfrost.io/#tag/cardano--governance/GET/governance/proposals/%tx_hash%7D/%cert_index%7D/metadata | API docs for Proposal metadata} + * + * @param txHash - Transaction Hash + * @param cert_index - Index of the certificate within the proposal transaction. + * @returns Proposal metadata information + * + */ +export async function proposalMetadata( + this: BlockFrostAPI, + txHash: string, + certIndex: number, +): Promise { + try { + const res = await this.instance( + `governance/proposals/${txHash}/${certIndex}/metadata`, + ); + return res.body; + } catch (error) { + throw handleError(error); + } +}