Feature: Add getPluginPreparations function (#294)

* add prepared plugins query

* update commons

* update changelog and example

* Update modules/client/src/types.ts

Co-authored-by: Michael Heuer <20623991+Michael-A-Heuer@users.noreply.github.com>

* fix formatting

* fix tests

---------

Co-authored-by: Michael Heuer <20623991+Michael-A-Heuer@users.noreply.github.com>

modules/client-common/CHANGELOG.md

@@ -18,6 +18,11 @@ TEMPLATE:
 -->
 
 ## [UPCOMING]
+### Added
+
+- Add new class error `InvalidPermissionOperationType`
+
+## [1.7.1]
 ### Fixed
 
 - ENS name Regex

modules/client-common/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aragon/sdk-client-common",
   "author": "Aragon Association",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "license": "MIT",
   "main": "dist/index.js",
   "module": "dist/sdk-client-common.esm.js",

modules/client-common/src/errors.ts

@@ -375,3 +375,9 @@ export class InvalidTimeoutError extends SdkError {
     );
   }
 }
+
+export class InvalidPermissionOperationType extends SdkError {
+  constructor(cause?: any) {
+    super("Invalid permission operation", cause);
+  }
+}

modules/client/CHANGELOG.md

@@ -18,7 +18,11 @@ TEMPLATE:
 -->
 
 ## [UPCOMING]
+### Added
+
+- `getPluginPreparations` function to `Client`
 
+## [1.16.3]
 ### Fixed
 
 - Required ensSubdomain in createDao

modules/client/examples/01-client/20-get-plugin-preparations.ts

@@ -0,0 +1,77 @@
+/* MARKDOWN
+---
+title: Get Plugin Preparations
+---
+
+## Get Plugin Preparations 
+
+Returns plugin preparations filtered by:
+
+- pluginAddress
+- daoAddressOrEns
+- pluginRepoAddress
+- type(Installation or Update)
+
+
+*/
+
+import {
+  Client,
+  PluginPreparationListItem,
+  PluginPreparationQueryParams,
+  PluginPreparationSortBy,
+} from "@aragon/sdk-client";
+import { SortDirection } from "@aragon/sdk-client-common";
+import { context } from "../index";
+
+// Instantiate the general purpose client from the Aragon OSx SDK context.
+const client: Client = new Client(context);
+
+const params: PluginPreparationQueryParams = {
+  limit: 10,
+  skip: 0,
+  direction: SortDirection.ASC,
+  sortBy: PluginPreparationSortBy.ID,
+  pluginAddress: "0x1234567890123456789012345678901234567890",
+  daoAddressOrEns: "0x1234567890123456789012345678901234567890",
+  pluginRepoAddress: "0x1234567890123456789012345678901234567890",
+};
+
+// Get a list of DAOs from the Aragon DAO registry.
+const pluginPreparations: PluginPreparationListItem[] = await client.methods
+  .getPluginPreparations(params);
+console.log(pluginPreparations);
+
+/* MARKDOWN
+Returns:
+
+```json
+[
+  {
+    id: string,
+    type: "Installation",
+    creator: "0x1234567890123456789012345678901234567890",
+    dao: "0x1234567890123456789012345678901234567890",
+    pluginRepo: {
+      id: "0x1234567890123456789012345678901234567890",
+      subdomain: "multisig"
+    },
+    versionTag: {
+      build: 1,
+      release: 1
+    },
+    pluginAddress: "0x1234567890123456789012345678901234567890",
+    permissions: [
+      {
+        who: "0x1234567890123456789012345678901234567890",
+        where: "0x1234567890123456789012345678901234567890",
+        permissionId: "0x12345678",
+        condition: "0x1234567890123456789012345678901234567890"
+      }
+    ]
+    helpers: ["0x1234567890123456789012345678901234567890"],;
+    data: new Uint8Array()
+  }
+]
+  ```
+*/

modules/client/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aragon/sdk-client",
   "author": "Aragon Association",
-  "version": "1.16.3",
+  "version": "1.17.0",
   "license": "MIT",
   "main": "dist/index.js",
   "module": "dist/sdk-client.esm.js",
@@ -62,7 +62,7 @@
   },
   "dependencies": {
     "@aragon/osx-ethers": "1.3.0-rc0.3",
-    "@aragon/sdk-client-common": "^1.7.1",
+    "@aragon/sdk-client-common": "^1.8.0",
     "@aragon/sdk-ipfs": "^1.1.0",
     "@ethersproject/abstract-signer": "^5.5.0",
     "@ethersproject/bignumber": "^5.6.0",

modules/client/src/internal/client/methods.ts

@@ -24,6 +24,7 @@ import {
   QueryIPlugin,
   QueryPlugin,
   QueryPluginPreparations,
+  QueryPluginPreparationsExtended,
   QueryPlugins,
   QueryTokenBalances,
   QueryTokenTransfers,
@@ -54,6 +55,9 @@ import {
   HasPermissionParams,
   IsDaoUpdateValidParams,
   IsPluginUpdateValidParams,
+  PluginPreparationListItem,
+  PluginPreparationQueryParams,
+  PluginPreparationSortBy,
   PluginQueryParams,
   PluginRepo,
   PluginRepoBuildMetadata,
@@ -75,6 +79,7 @@ import {
   SubgraphDao,
   SubgraphDaoListItem,
   SubgraphPluginInstallation,
+  SubgraphPluginPreparationListItem,
   SubgraphPluginRepo,
   SubgraphPluginRepoListItem,
   SubgraphPluginRepoRelease,
@@ -93,6 +98,7 @@ import {
   toAssetBalance,
   toDaoDetails,
   toDaoListItem,
+  toPluginPreparationListItem,
   toPluginRepo,
   toTokenTransfer,
 } from "../utils";
@@ -168,6 +174,7 @@ import {
   HasPermissionSchema,
   IsDaoUpdateValidSchema,
   IsPluginUpdateValidSchema,
+  PluginPreparationQuerySchema,
   PluginQuerySchema,
 } from "../schemas";
 
@@ -1527,4 +1534,64 @@ export class ClientMethods extends ClientCore implements IClientMethods {
     );
     return daoFactoryImplementation.daoBase();
   }
+
+  public async getPluginPreparations(
+    {
+      type,
+      pluginAddress,
+      pluginRepoAddress,
+      daoAddressOrEns,
+      limit = 10,
+      skip = 0,
+      direction = SortDirection.ASC,
+      sortBy = PluginPreparationSortBy.ID,
+    }: PluginPreparationQueryParams,
+  ): Promise<PluginPreparationListItem[]> {
+    await PluginPreparationQuerySchema.strict().validate({
+      type,
+      pluginAddress,
+      pluginRepoAddress,
+      daoAddressOrEns,
+      limit,
+      skip,
+      direction,
+      sortBy,
+    });
+
+    let where = {};
+    if (type) {
+      where = { ...where, type };
+    }
+    if (pluginAddress) {
+      where = { ...where, pluginAddress: pluginAddress.toLowerCase() };
+    }
+    if (pluginRepoAddress) {
+      where = { ...where, pluginRepoAddress: pluginRepoAddress.toLowerCase() };
+    }
+    if (daoAddressOrEns) {
+      where = { ...where, dao: daoAddressOrEns.toLowerCase() };
+    }
+    const query = QueryPluginPreparationsExtended;
+    const params = {
+      where,
+      limit,
+      skip,
+      direction,
+      sortBy,
+    };
+    const name = "plugin preparations";
+    type T = { pluginPreparations: SubgraphPluginPreparationListItem[] };
+    const { pluginPreparations } = await this.graphql.request<T>({
+      query,
+      params,
+      name,
+    });
+    return Promise.all(
+      pluginPreparations.map(
+        (pluginPreparation: SubgraphPluginPreparationListItem) => {
+          return toPluginPreparationListItem(pluginPreparation);
+        },
+      ),
+    );
+  }
 }

modules/client/src/internal/graphql-queries/plugin.ts

@@ -63,3 +63,36 @@ query PluginPreparations($where: PluginUpdatePreparation_filter!) {
   }
 }
 `;
+
+export const QueryPluginPreparationsExtended = gql`
+query PluginPreparations($where: PluginUpdatePreparation_filter!, limit: Int!, skip: Int!, direction: OrderDirection!, sortBy: PluginUpdatePreparation_orderBy!) {
+  pluginPreparations(where: $where, first: $limit, skip: $skip, orderDirection: $direction, orderBy: $sortBy){
+    id
+    type
+    creator
+    dao {
+      id
+    }
+    pluginRepo {
+      id
+      subdomain
+    }
+    pluginVersion{
+      build
+      release{
+        release
+      }
+    }
+    pluginAddress
+    permissions {
+      id
+      operation
+      where
+      who
+      condition
+    }
+    helpers
+    data
+  }
+}
+`;

modules/client/src/internal/interfaces.ts

@@ -1,19 +1,22 @@
 // This file contains the definitions of the general purpose DAO client
 import {
   ApplyInstallationParams,
+  ApplyUninstallationParams,
   ApplyUpdateParams,
   DaoAction,
   DecodedApplyInstallationParams,
+  DecodedApplyUninstallationParams,
   DecodedApplyUpdateParams,
   GasFeeEstimation,
   InterfaceParams,
   PrepareInstallationParams,
   PrepareInstallationStepValue,
+  PrepareUninstallationParams,
+  PrepareUninstallationStepValue,
   PrepareUpdateParams,
   PrepareUpdateStepValue,
 } from "@aragon/sdk-client-common";
 import {
-  ApplyUninstallationParams,
   AssetBalance,
   CreateDaoParams,
   DaoBalancesQueryParams,
@@ -26,20 +29,19 @@ import {
   DaoUpdateDecodedParams,
   DaoUpdateParams,
   DaoUpdateProposalValidity,
-  DecodedApplyUninstallationParams,
   DepositParams,
   GrantPermissionDecodedParams,
   GrantPermissionParams,
   GrantPermissionWithConditionParams,
   HasPermissionParams,
   InitializeFromParams,
   IsDaoUpdateValidParams,
+  PluginPreparationListItem,
+  PluginPreparationQueryParams,
   PluginQueryParams,
   PluginRepo,
   PluginRepoListItem,
   PluginUpdateProposalValidity,
-  PrepareUninstallationParams,
-  PrepareUninstallationStepValue,
   RegisterStandardCallbackParams,
   RevokePermissionDecodedParams,
   RevokePermissionParams,
@@ -114,6 +116,10 @@ export interface IClientMethods {
   getDaoImplementation: (
     daoFactoryAddress: string,
   ) => Promise<string>;
+
+  getPluginPreparations(
+    params: PluginPreparationQueryParams,
+  ): Promise<PluginPreparationListItem[]>;
 }
 
 export interface IClientEncoding {

modules/client/src/internal/schemas.ts

@@ -9,6 +9,7 @@ import {
   Uint8ArraySchema,
 } from "@aragon/sdk-client-common";
 import { array, mixed, number, object, string } from "yup";
+import { PluginPreparationSortBy, PluginPreparationType } from "../types";
 
 export const CreateDaoSchema = object({
   metadataUri: IpfsUriSchema.required(),
@@ -187,3 +188,13 @@ export const IsDaoUpdateValidSchema = object({
   daoAddress: AddressOrEnsSchema.required(),
   version: array().of(number()).length(3).notRequired(),
 });
+export const PluginPreparationQuerySchema = PaginationSchema.concat(object({
+  sortBy: string().notRequired().oneOf([PluginPreparationSortBy.ID]),
+  type: string().notRequired().oneOf([
+    PluginPreparationType.INSTALLATION,
+    PluginPreparationType.UPDATE,
+  ]),
+  daoAddressOrEns: AddressOrEnsSchema.notRequired(),
+  pluginAddress: AddressOrEnsSchema.notRequired(),
+  pluginRepoAddress: AddressOrEnsSchema.notRequired(),
+}));