Access grant queries

.github/workflows/e2e-node.yml

@@ -50,3 +50,4 @@ jobs:
           E2E_TEST_OWNER_CLIENT_ID: ${{ secrets.E2E_TEST_OWNER_CLIENT_ID }}
           E2E_TEST_OWNER_CLIENT_SECRET: ${{ secrets.E2E_TEST_OWNER_CLIENT_SECRET }}
           E2E_TEST_FEATURE_RECURSIVE_ACCESS_GRANTS: ${{ secrets.E2E_TEST_FEATURE_RECURSIVE_ACCESS_GRANTS }}
+          E2E_TEST_FEATURE_QUERY_ENDPOINT: ${{ secrets.E2E_TEST_FEATURE_QUERY_ENDPOINT }}

CHANGELOG.md

@@ -6,18 +6,26 @@ This project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html
 
 The following changes are pending, and will be applied on the next major release:
 
-- The `status` parameter for `getAccessGrantAll` will default to `all` rather than `granted`.
+- The `getAccessGrantAll` function is deprecated. It can be replaced with `query`.
+  Although the two functions' behavior is different, they can be used to achieve
+  similar results.
+- The `gConsent` and all of `gConsent/*` submodules are deprecated. The former can
+  be replaced by a regular import of the library, and the latter can be replaced
+  with the equivalent non-gConsent submodules (e.g. `gConsent/manage` can be replaced
+  with `manage`). There is no functionality change between the two.
 
 ## Unreleased
 
-### New feature (alpha)
+### New feature
 
 - Add support for custom fields. Applications are now able to read and write custom fields
   into Access Credentials (both Access Requests and Access Grants). This feature is available
   via a new option introduced in `issueAccessRequest` and `approveAccessRequest` to write the
   custom fields, and via a set of dedicated getters in the `getters/` module. A generic getter
   is introduced, `getCustomFields`, as well as a set of typed helpers, such as `getCustomInteger`.
   Typed helpers are available for integers, floats, strings and booleans.
+- Support new query endpoint: the new `query` function enables querying for Access Credentials using
+  the newly introduced ESS endpoint.
 
 ## [3.1.1](https://github.com/inrupt/solid-client-access-grants-js/releases/tag/v3.1.1) - 2024-10-23
 

e2e/node/e2e.test.ts

@@ -52,6 +52,7 @@ import * as sc from "@inrupt/solid-client";
 import { custom } from "openid-client";
 import type { AccessGrant, AccessRequest } from "../../src/index";
 import {
+  DURATION,
   approveAccessRequest,
   createContainerInContainer,
   denyAccessRequest,
@@ -71,6 +72,7 @@ import {
   isValidAccessGrant,
   issueAccessRequest,
   overwriteFile,
+  query,
   revokeAccessGrant,
   saveFileInContainer,
   saveSolidDatasetAt,
@@ -1712,4 +1714,61 @@ describe(`End-to-end access grant tests for environment [${environment}] `, () =
       });
     },
   );
+
+  describeIf(environmentFeatures?.QUERY_ENDPOINT === "true")(
+    "query endpoint",
+    () => {
+      it("can navigate the paginated results", async () => {
+        const allCredentialsPageOne = await query(
+          { pageSize: 10 },
+          {
+            fetch: addUserAgent(requestorSession.fetch, TEST_USER_AGENT),
+            // FIXME add query endpoint discovery check.
+            queryEndpoint: new URL("query", vcProvider),
+          },
+        );
+        // We should get the expected page length.
+        expect(allCredentialsPageOne.items).toHaveLength(10);
+        // The first page should not have a "prev" link.
+        expect(allCredentialsPageOne.prev).toBeUndefined();
+        expect(allCredentialsPageOne.next).toBeDefined();
+
+        // Go to the next result page
+        const allCredentialsPageTwo = await query(allCredentialsPageOne.next!, {
+          fetch: addUserAgent(requestorSession.fetch, TEST_USER_AGENT),
+          // FIXME add query endpoint discovery check.
+          queryEndpoint: new URL("query", vcProvider),
+        });
+        expect(allCredentialsPageTwo.items).toHaveLength(10);
+      });
+
+      it("can filter based on one or more criteria", async () => {
+        const onType = await query(
+          { type: "SolidAccessGrant" },
+          {
+            fetch: addUserAgent(requestorSession.fetch, TEST_USER_AGENT),
+            // FIXME add query endpoint discovery check.
+            queryEndpoint: new URL("query", vcProvider),
+          },
+        );
+        expect(onType.items).not.toHaveLength(0);
+        const onTypeAndStatus = await query(
+          {
+            type: "SolidAccessGrant",
+            status: "Active",
+            issuedWithin: DURATION.ONE_DAY,
+          },
+          {
+            fetch: addUserAgent(requestorSession.fetch, TEST_USER_AGENT),
+            // FIXME add query endpoint discovery check.
+            queryEndpoint: new URL("query", vcProvider),
+          },
+        );
+        expect(onTypeAndStatus.items).not.toHaveLength(0);
+        expect(onTypeAndStatus.items.length).toBeLessThanOrEqual(
+          onType.items.length,
+        );
+      });
+    },
+  );
 });

package.json

@@ -45,6 +45,7 @@
     "./fetch": "./dist/resource/index.mjs",
     "./discover": "./dist/gConsent/discover/index.mjs",
     "./manage": "./dist/gConsent/manage/index.mjs",
+    "./query": "./dist/gConsent/query/query.mjs",
     "./request": "./dist/gConsent/request/index.mjs",
     "./verify": "./dist/common/verify/index.mjs",
     "./getters": "./dist/common/getters.mjs",
@@ -61,6 +62,9 @@
       "manage": [
         "dist/gConsent/manage/index.d.ts"
       ],
+      "query": [
+        "dist/gConsent/query/query.d.ts"
+      ],
       "request": [
         "dist/gConsent/request/index.d.ts"
       ],
@@ -131,7 +135,7 @@
   "dependencies": {
     "@inrupt/solid-client": "^2.0.0",
     "@inrupt/solid-client-errors": "^0.0.2",
-    "@inrupt/solid-client-vc": "^1.1.2",
+    "@inrupt/solid-client-vc": "^1.2.0",
     "@types/rdfjs__dataset": "^2.0.7",
     "auth-header": "^1.0.0",
     "base64url": "^3.0.1",

src/gConsent/index.ts

@@ -45,6 +45,15 @@ export {
   getAccessGrantFromRedirectUrl,
 } from "./request";
 
+export {
+  CredentialFilter,
+  CredentialResult,
+  CredentialStatus,
+  CredentialType,
+  DURATION,
+  query,
+} from "./query/query";
+
 export {
   approveAccessRequest,
   denyAccessRequest,

src/gConsent/manage/getAccessGrantAll.ts

@@ -126,6 +126,7 @@ const getAncestorUrls = (resourceUrl: URL) => {
  *   with the environment you are requesting against.
  * @returns A promise resolving to an array of Access Grants matching the request.
  * @since 0.4.0
+ * @deprecated Use the new `query` method instead.
  */
 async function getAccessGrantAll(
   params: AccessParameters,
@@ -134,7 +135,7 @@ async function getAccessGrantAll(
   },
 ): Promise<Array<DatasetWithId>>;
 /**
- * @deprecated Please set returnLegacyJsonld: false and use RDFJS API
+ * @deprecated Use the new `query` method instead.
  */
 async function getAccessGrantAll(
   params: AccessParameters,
@@ -143,7 +144,7 @@ async function getAccessGrantAll(
   },
 ): Promise<Array<VerifiableCredential>>;
 /**
- * @deprecated Please set returnLegacyJsonld: false and use RDFJS API
+ * @deprecated Use the new `query` method instead.
  */
 async function getAccessGrantAll(
   params: AccessParameters,